# @qa-gentic/stlc-agents — Jira Cloud Quick Start

> Jira Cloud pipeline: issue → test cases → Gherkin → Playwright TypeScript → Helix-QA.
> For Azure DevOps see [QUICKSTART-ADO.md](QUICKSTART-ADO.md).


Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.

[![npm version](https://img.shields.io/npm/v/@qa-gentic/stlc-agents)](https://www.npmjs.com/package/@qa-gentic/stlc-agents)
[![PyPI version](https://img.shields.io/pypi/v/qa-gentic-stlc-agents)](https://pypi.org/project/qa-gentic-stlc-agents/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---


## What the Jira Pipeline Does

Six Python MCP servers. The Jira pipeline uses `qa-jira-manager` as its entry point, then the three shared agents, with `qa-migration` / `stlc-migrate` available for converting existing Playwright projects:

| Step | Agent | What happens |
|---|---|---|
| 1 | `qa-jira-manager` | Fetch Jira issue + analyse acceptance criteria |
| 2 | `qa-jira-manager` | Generate test cases → create in Jira with `is tested by` links |
| 3 | `qa-gherkin-generator` | Generate Gherkin `.feature` file |
| 4 | `qa-playwright-generator` | Gherkin + live browser → self-healing Playwright TypeScript |
| 5 | `qa-helix-writer` | Write generated files to Helix-QA project on disk |
| — | `qa-migration` / `stlc-migrate` | Existing Playwright project → fully agent-ready Helix-QA tree (Jira `.mcp.json`, skills, healer scaffold, BOILERPLATE infra) |

The Playwright MCP server (`http://localhost:8931/mcp`) is required for browser-driven code generation. It is not part of this package and must be started separately.

---

## Install

```bash
npm install -g @qa-gentic/stlc-agents
qa-stlc init --vscode --integration jira
```


`qa-stlc init --integration jira` performs:
1. `pip install qa-gentic-stlc-agents` — installs all six Python MCP servers + `stlc-migrate` CLI
2. Copies skill files (including `qa-jira-manager/`, `generate-gherkin/`, `generate-playwright-code/`, `write-helix-files/`, `migrate-framework/`) to your coding agent directory
3. Writes `.vscode/mcp.json` with all required servers configured (`qa-jira-manager` + shared Agents 2–4 + `qa-migration` + `playwright`)


Start the Playwright MCP server before your first session:

```bash
npx @playwright/mcp@latest --port 8931
```

---


## Requirements

- Node.js ≥ 18
- Python ≥ 3.10, < 3.14
- Jira Cloud site with OAuth 2.0 credentials (see [Authentication Setup](#authentication-setup))
- A `.env` file containing:


```env
# Jira Cloud credentials
JIRA_CLIENT_ID=your-atlassian-oauth-client-id
JIRA_CLIENT_SECRET=your-atlassian-oauth-client-secret
JIRA_CLOUD_ID=your-atlassian-cloud-id
# Optional — defaults to http://localhost:8765/callback
# JIRA_REDIRECT_URI=http://localhost:8765/callback

# Application under test
APP_BASE_URL=https://your-app.example.com
APP_EMAIL=your-test-email@example.com
APP_PASSWORD=your-test-password
```

---

## 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 scopes: `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-valid-token>" \
  https://api.atlassian.com/oauth/token/accessible-resources
```

Copy the `id` field for your Jira 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
```

### Step 4 — First run

On first use a browser opens once for sign-in. The token is cached at `~/.jira-cache/jira-token.json` and silently refreshed for ~60 days.

---


## Commands

All `qa-stlc` commands accept `--integration jira`:

```bash
qa-stlc init [--vscode] [--python <path>] --integration jira
# Full bootstrap: pip install + Jira skills + MCP config with all 5 agents

qa-stlc mcp-config [--vscode] [--print] [--python <path>] --integration jira
# Write MCP config including qa-jira-manager + shared agents

qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print] --integration jira
# Install Jira + shared skill files (excludes ADO-only generate-test-cases/)

qa-stlc verify --integration jira
# Check all 6 MCP servers are installed + Jira auth cache exists

qa-stlc scaffold [--name <n>] [--dir <path>]
# Scaffold a new Playwright + Cucumber + TypeScript QA project (same as ADO)

stlc-migrate --source <existing> --helix <target> --integration jira [--conflict overwrite|skip|interactive] [--preserve-tree] [--features=vrt] [--dry-run] [--json]
# Migrate an existing Playwright (with or without Cucumber) project into the
# Helix-QA layout, Jira variant. Installs Jira-only skills + .mcp.json with
# qa-jira-manager (incl. JIRA_CLIENT_ID/SECRET/CLOUD_ID env passthrough),
# the enhanced healer scaffold (LocatorHealer 8-strategy chain, LocatorRepository
# schema v1, HealingDashboard with write-back), AGENT-BEHAVIOR.md,
# ORCHESTRATION_RULES.md, and the 11-file BOILERPLATE allowlist. See
# `skills/migrate-framework/SKILL.md` for the full pipeline reference.
```

### Makefile shortcuts

```bash
make bootstrap-jira                                       # one-shot: Jira skills + .mcp.json
make migrate-jira SOURCE=<old> HELIX=<new>                # Jira migration with sensible defaults
make migrate-jira SOURCE=<old> HELIX=<new> CONFLICT=overwrite   # re-migrate in place
make audit-migration HELIX=<new>                          # framework_state + skills + healer scaffold + heal-store report
```

---

## Usage

Open your AI coding agent and use natural language:

```
# Full Jira pipeline — single prompt
Run the full STLC pipeline for Jira issue PROJ-123

# Step by step
Fetch Jira issue PROJ-123 and analyse acceptance criteria
Generate test cases for PROJ-123 and create them in Jira
Generate Gherkin feature file for PROJ-123
Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login
Write the generated files to my Helix-QA project at /workspace/my-qa-project
```

---

## Tool Reference


### qa-jira-manager

| Tool | Description |
|---|---|
| `fetch_jira_issue` | Fetch a Story, Bug, Task, or Sub-task with acceptance criteria and coverage hints. Routes Epics to `fetch_jira_epic_hierarchy`. |
| `fetch_jira_epic_hierarchy` | Fetch an Epic and 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 them via `is tested by`. Steps stored as ADF table — no Xray required. Returns `confirmation_required: true` for Epics. |
| `get_linked_test_cases` | Return all test cases already linked to a Jira issue. Call before generating to power the deduplication gate. |

### qa-gherkin-generator (shared)

| Tool | Description |
|---|---|
| `fetch_work_item_for_gherkin` | Fetch a work item with AC context for Gherkin generation (pass Jira issue key). |
| `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |
| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file (for Jira pipeline: saves locally or attaches via Jira REST). |

### qa-playwright-generator (shared)

| Tool | Description |
|---|---|
| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts` from validated Gherkin + live AX-tree `context_map`. Blocks if `context_map` is absent. |
| `scaffold_locator_repository` | Generate the six Helix-QA healing infrastructure files. |
| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |

### qa-helix-writer (shared)

| Tool | Description |
|---|---|
| `inspect_helix_project` | Returns `framework_state` (`present` / `partial` / `absent`) and `recommendation`. |
| `list_helix_tree` | List the full directory tree of a Helix-QA project. |
| `read_helix_file` | Read an existing file for overlap detection. |
| `write_helix_files` | Write generated files to the correct Helix-QA paths. |

### playwright (external)

| Tool | Description |
|---|---|
| `browser_navigate` | Navigate to a URL in the live browser. |
| `browser_snapshot` | Capture the full AX tree — source for zero-hallucination locators. |
| `browser_fill_form` | Fill multiple form fields by ref. |
| `browser_click` | Click an element by ref. |

---

## MCP Config

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

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

### Claude Code (`.mcp.json`)

```json
{
  "mcpServers": {
    "qa-jira-manager":         { "command": "/path/to/.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/to/.venv/bin/qa-gherkin-generator" },
    "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
    "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
    "qa-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--isolated"] }
  }
}
```

> Run `qa-stlc mcp-config --integration jira [--vscode]` to generate this
> manually, or run `stlc-migrate --integration jira` and the migration emits
> `.mcp.json` automatically with absolute binary paths discovered from the
> active venv.

---


## Skills Installed (Jira integration)

| Skill | Purpose |
|---|---|
| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
| `qa-jira-manager/` | Jira fetch, test case creation, and full pipeline orchestration |
| `generate-gherkin/` | Gherkin generation from issue AC |
| `generate-playwright-code/` | Gherkin + live browser → self-healing Playwright TypeScript |
| `write-helix-files/` | Generated files → Helix-QA disk layout |
| `deduplication-protocol/` | READ → DIFF → CREATE mandatory pre-flight gate |

> `generate-test-cases/` is excluded for Jira-only installs — it is ADO work-item-scoped.

---

## Three-Layer Self-Healing Architecture

Same as the ADO pipeline — the generated Playwright code uses identical healing infrastructure:

| Layer | Class | What it heals |
|---|---|---|
| 1 — Locator | `LocatorHealer` | 8-strategy chain: cached → primary → **attribute (intent-shape-aware)** → **type-hint** → role → label → text → AI Vision. After match, introspects the live element and persists a specific single-attribute selector (`#id`, `[data-testid=…]`, etc.). Attribute strategy uses `:is(input, textarea, …)[id*="…"]` so an intent like `"password input"` can't match an unrelated `<a id="forgot-password">`. |
| 2 — Timing | `TimingHealer` | Network-trace drift → auto-adjusted timeouts → HealingDashboard |
| 3 — Visual | `VisualIntentChecker` | Element screenshot diff at assertions → HealingDashboard |

Refer to [ARCHITECTURE-ADO.md § Three-Layer Self-Healing Architecture](ARCHITECTURE-ADO.md#three-layer-self-healing-architecture) for full strategy ordering, env-var tuning (`HEAL_STRATEGY_ORDER`, `LOCATOR_TIMEOUT`, `LOCATOR_HEAL_ATTEMPTS`, etc.), and HealingDashboard write-back behaviour.

---

## Run Tests

```bash
ENABLE_SELF_HEALING=true \
HEALING_DASHBOARD_PORT=7890 \
APP_BASE_URL=<your-app-base-url> \
APP_EMAIL=<email> \
APP_PASSWORD=<password> \
cucumber-js --config=config/cucumber.js -p <feature_profile>
```

### Inspect healed locators (migrated projects only)

```bash
ENV=qa4 npm run healix:dashboard   # http://localhost:7890 — Confirm / Revert
ENV=qa4 npm run healix:review      # http://localhost:7891 — read-only mirror
cat self-heals/healed-locators.qa4.json | jq .
tail self-heals/heal.log
```

Confirm on a healed entry rewrites the source `*.locators.ts` file's
`selector:` field — future runs use it as the primary probe.

---

## Documentation

- [Quick Start: Azure DevOps](QUICKSTART-ADO.md)
- [Quick Start: Jira Cloud](QUICKSTART-JIRA.md)
- [Architecture: ADO](ARCHITECTURE-ADO.md)
- [Architecture: Jira](ARCHITECTURE-JIRA.md)
- [Walkthrough: ADO](WALKTHROUGH-ADO.md)
- [Walkthrough: Jira](WALKTHROUGH-JIRA.md)

---

## License

MIT
