# STLC Agents — Architecture: Jira Cloud Pipeline

> Technical reference for the Jira Cloud pipeline.
> For the Azure DevOps pipeline see [ARCHITECTURE-ADO.md](ARCHITECTURE-ADO.md).

---

## System Overview

The Jira Cloud pipeline runs the same full STLC as the ADO pipeline. `qa-jira-manager` replaces `qa-test-case-manager` as the entry point and manages Jira OAuth 2.0 (3LO) authentication. Agents 2–4 (`qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`) are shared between both pipelines and behave identically.

| Agent | Role | Pipeline |
|---|---|---|
| `qa-jira-manager` | Fetch Jira issues, generate and link test cases | Jira only |
| `qa-gherkin-generator` | Generate `.feature` files from acceptance criteria | Shared |
| `qa-playwright-generator` | Generate self-healing Playwright TypeScript | Shared |
| `qa-helix-writer` | Write generated files to Helix-QA disk layout | Shared |

---

## Data Flow

```
Jira Issue (Story / Bug / Task / Epic)
         │
         │  Agent 5: qa-jira-manager
         ├─ fetch_jira_issue / fetch_jira_epic_hierarchy
         ├─ get_linked_test_cases → deduplication
         └─ create_and_link_test_cases → Jira test case issues ("is tested by")
                   │
                   ▼
         Jira Test Case Issues linked to source story
                   │
                   │  Agent 2: qa-gherkin-generator
                   ├─ generate .feature from AC
                   └─ save locally or attach to Jira issue
                             │
                             ▼
                    Gherkin .feature file
                             │
                             │  Playwright MCP (external)
                             ├─ browser_navigate → live app page
                             └─ browser_snapshot → AX tree → context_map
                                       │
                                       │  Agent 3: qa-playwright-generator
                                       ├─ generate_playwright_code → 4 TS files per feature
                                       ├─ scaffold_locator_repository → 5 infra files
                                       └─ save locally or attach to Jira issue
                                                 │
                                                 │  Agent 4: qa-helix-writer
                                                 └─ write_helix_files → Helix-QA disk layout
                                                           │
                                                           ▼
                                              cucumber-js test run + HealingDashboard :7890
```

---

## Agent 5 — `qa-jira-manager`

**Purpose:** Run the full Jira STLC pipeline — fetch Jira issues, generate and create test cases in Jira with `is tested by` links, then hand off to Agents 2–4.

### Tools

| Tool | Description |
|---|---|
| `fetch_jira_issue` | Fetch a Story, Bug, Task, or Sub-task from Jira Cloud with AC and coverage hints. Returns `epic_use_hierarchy` for Epics. |
| `fetch_jira_epic_hierarchy` | Fetch a Jira Epic and enumerate all child issues (Stories, Tasks, Bugs, Sub-tasks). |
| `create_and_link_test_cases` | Create test case issues in Jira (type `Test`, falls back to `Task`) and link via `is tested by`. Steps stored as ADF table — no Xray required. Returns `confirmation_required: true` for Epics. |
| `get_linked_test_cases` | Return test cases already linked to a Jira issue (deduplication). |

### Coverage Hint Extraction

Identical to Agent 1 — scans acceptance criteria for 11 categories:

```
toast_notifications  file_size_boundary  post_action_state  platform_specific
computed_values      data_persistence    accessibility       image_manipulation
file_formats         cancel_flows        validation_errors
```

### Jira-Specific Behaviours

- Test cases are Jira issues of type `Test` (falls back to `Task` — no Xray required)
- Steps stored as ADF (Atlassian Document Format) tables in the issue description
- Links use `is tested by` / `Test` Jira link type
- Epic ID → returns `epic_use_hierarchy` to route to `fetch_jira_epic_hierarchy`
- `confirmation_required: true` returned for Epic-level creation before any action

---

## Authentication — Jira OAuth 2.0 (3LO)

Agent 5 uses `shared_jira/auth.py`. Token cached at `~/.jira-cache/jira-token.json` and silently refreshed for approximately 60 days.

### Token Acquisition Sequence

```
1. Load ~/.jira-cache/jira-token.json
2. Attempt silent token refresh  →  if valid, Bearer token returned (zero UI)
3. If expired: browser opens once for Jira sign-in → token cached ~60 days
CI/CD: JIRA_CLIENT_ID + JIRA_CLIENT_SECRET + JIRA_CLOUD_ID → no browser
```

### Setup Steps

1. Go to <https://developer.atlassian.com/console/myapps/> → Create → OAuth 2.0 integration
2. Add callback URL: `http://localhost:8765/callback`
3. Enable permissions: `read:jira-user`, `read:jira-work`, `write:jira-work`, `offline_access`
4. Find your Cloud ID:
   ```bash
   curl https://api.atlassian.com/oauth/token/accessible-resources
   ```
5. Add to `.env`:
   ```env
   JIRA_CLIENT_ID=your-client-id
   JIRA_CLIENT_SECRET=your-client-secret
   JIRA_CLOUD_ID=your-cloud-id
   ```

---

## Shared Pipeline — Agents 2–4

These agents are identical in both pipelines. See [ARCHITECTURE-ADO.md](ARCHITECTURE-ADO.md) for full detail on each. Key differences in the Jira context:

### Agent 2 — `qa-gherkin-generator`

In the Jira pipeline, acceptance criteria are sourced from `fetch_jira_issue` or `fetch_jira_epic_hierarchy` rather than ADO API calls. The same 5-tool interface, Gherkin rules, and validation logic applies. Feature files can be saved locally or attached to the Jira issue — the agent asks explicitly rather than inferring.

### Agent 3 — `qa-playwright-generator`

Identical in both pipelines. Requires `context_map` from Playwright MCP `browser_snapshot`. Hard-blocks if absent. Generates the same per-feature TypeScript files and the same shared infrastructure files (see ARCHITECTURE-ADO.md for the full breakdown — `LocatorHealer.ts`, `LocatorRepository.ts`, `TimingHealer.ts`, `VisualIntentChecker.ts`, `HealingDashboard.ts`, `dashboard-server.ts`, plus the BOILERPLATE-filled strategy / rules / apply layer). Code can be attached to the Jira issue or saved locally.

### Agent 4 — `qa-helix-writer`

Identical in both pipelines. No ADO or Jira dependency. Writes files to the Helix-QA directory layout on disk. The `inspect_helix_project` tool verifies `LocatorHealer.ts` + `LocatorRepository.ts` exist; in a migrated tree these come from `stlc-migrate`'s enhanced scaffolds, not the BOILERPLATE versions.

### Self-Healing Architecture

Refer to [ARCHITECTURE-ADO.md § Three-Layer Self-Healing Architecture](ARCHITECTURE-ADO.md#three-layer-self-healing-architecture) — the chain (cached → primary → attribute → type-hint → role → label → text → AI Vision), the post-match specific-selector introspection, and the HealingDashboard write-back-to-source behaviour are identical regardless of whether the test data originated in ADO or Jira.

---

## Pipeline Comparison: ADO vs Jira

| Aspect | Azure DevOps | Jira Cloud |
|---|---|---|
| Entry agent | `qa-test-case-manager` | `qa-jira-manager` |
| Work item fetch | ADO REST API | Jira REST API v3 |
| Test case storage | ADO Test Case work items | Jira issues of type `Test` or `Task` |
| Link type | `TestedBy-Forward` | `is tested by` / `Test` |
| Step format | `Microsoft.VSTS.TCM.Steps` XML | ADF table in issue description |
| Authentication | MSAL (`~/.msal-cache/`) | OAuth 2.0 3LO (`~/.jira-cache/`) |
| Epic support | Not supported — warn user | `fetch_jira_epic_hierarchy` |
| Gherkin delivery | `attach_gherkin_to_work_item` (ADO attachment) | Save locally or attach to Jira issue |
| Code delivery | `attach_code_to_work_item` (ADO attachment) | Save locally or attach to Jira issue |

---

## MCP Configuration

**VS Code / GitHub Copilot (`.vscode/mcp.json`):**

```json
{
  "servers": {
    "qa-jira-manager": {
      "command": "/path/.venv/bin/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}"
      }
    },
    "qa-gherkin-generator":    { "command": "/path/.venv/bin/qa-gherkin-generator" },
    "qa-playwright-generator": { "command": "/path/.venv/bin/qa-playwright-generator" },
    "qa-helix-writer":         { "command": "/path/.venv/bin/qa-helix-writer" },
    "qa-migration":            { "command": "/path/.venv/bin/stlc-migrate" },
    "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
  }
}
```

Use `qa-stlc mcp-config --vscode --integration jira` to generate this
manually, or let `stlc-migrate --integration jira` emit it automatically
as part of a migration.

---

## Migration (Existing Playwright project → Helix-QA, Jira variant)

```bash
stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration jira \
  [--preserve-tree] [--features=vrt] [--conflict overwrite|skip|interactive]
```

`--integration jira` installs only the Jira-relevant skills
(`qa-jira-manager`, plus the shared Gherkin / Playwright / Helix-writer /
deduplication / migrate-framework skills) and writes a `.mcp.json` whose
`qa-jira-manager` entry includes the `JIRA_CLIENT_ID` / `JIRA_CLIENT_SECRET`
/ `JIRA_CLOUD_ID` env passthroughs above. Everything else (healer scaffold,
`.env.example`, BOILERPLATE fill, etc.) is identical to the ADO case — see
`skills/migrate-framework/SKILL.md` for the full pipeline reference.