npm package: @qa-gentic/stlc-agents
Description: QA STLC Agents — five MCP servers + skills for AI-powered test case, Gherkin, Playwright generation, and Helix-QA file writing against Azure DevOps and Jira Cloud. Full pipeline for both: fetch → test cases → Gherkin → Playwright → Helix-QA. Works with Cl
Latest version: 1.0.16

# @qa-gentic/stlc-agents

> AI-powered QA STLC automation — from Azure DevOps **or Jira Cloud** work item to self-healing Playwright TypeScript in a Helix-QA project.

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

![npm version](https://img.shields.io/badge/npm-v1.0.10-blue)
![PyPI version](https://img.shields.io/badge/pypi-v1.0.10-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![Python >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)

---

## What It Does

Five Python MCP servers cover the full QA Software Test Life Cycle:

| Agent | Input | Output |
|---|---|---|
| `qa-test-case-manager` | ADO PBI / Bug / Feature ID | Manual test cases created & linked via TestedBy-Forward |
| `qa-gherkin-generator` | ADO / Jira Epic / Feature / PBI / Bug ID | `.feature` file attached to ADO work item or saved locally |
| `qa-playwright-generator` | Gherkin + live browser | `locators.ts` + page objects + step defs attached to ADO or saved locally |
| `qa-helix-writer` | Generated `.ts` files + `helix_root` | Files written to Helix-QA directory layout on disk |
| `qa-jira-manager` | **Jira** Story / Bug / Task / Epic | Test cases created in Jira → Gherkin → Playwright TypeScript → Helix-QA files |

A sixth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a real browser during code generation, replacing hand-authored locators with accessibility-tree-derived, zero-hallucination selectors.

> **ADO or Jira?** Both pipelines now run the full STLC: fetch → analyse → test cases → Gherkin → Playwright → Helix-QA. ADO uses `qa-test-case-manager` as the entry point; Jira uses `qa-jira-manager`. Agents 2–4 (`qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`) are shared by both pipelines.

---

## Install


```bash
# 1. Install the CLI + npm package globally
#    You will be prompted to choose your integration: ado / jira / both
#    The choice is saved to ~/.qa-stlc/integration and reused by all subsequent commands.
npm install -g @qa-gentic/stlc-agents
```

> **Note:** On most systems, the installer will prompt you to select your integration (ADO, Jira, or both) and then automatically run `qa-stlc init` and offer to scaffold a new project. If you do **not** see the prompt (for example, if npm skips postinstall for an already-installed package, or in some non-interactive environments), simply run:
>
> ```bash
> qa-stlc init
> qa-stlc scaffold
> ```
> 
> This will perform the same setup steps as the postinstall script.

```bash
# 2. Bootstrap your project (installs Python agents, copies skills, writes MCP config)
#    --integration overrides the saved preference; omit to reuse the choice from step 1.
qa-stlc init --vscode --integration ado    # GitHub Copilot / VS Code — ADO pipeline
qa-stlc init --vscode --integration jira   # GitHub Copilot / VS Code — Jira pipeline
qa-stlc init --vscode --integration both   # GitHub Copilot / VS Code — both pipelines
# or for Claude Code (no --vscode flag):
qa-stlc init --integration ado

# 3. Scaffold a new Playwright + Cucumber + TypeScript QA project
qa-stlc scaffold --name my-qa-project
# or into an existing directory
qa-stlc scaffold --name acme-e2e --dir /path/to/acme-e2e

# 4. Start the Playwright browser server (required for code generation)
npx @playwright/mcp@latest --port 8931
```

`qa-stlc init` does four things:
1. `pip install qa-gentic-stlc-agents` — installs all five Python MCP servers
2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
3. Copies custom agent files to `.github/agents/` (used by GitHub Copilot and Claude's agent picker)
4. Writes `.vscode/mcp.json` with all six servers configured

> **Integration flag:** `--integration` controls which agents and skill files are installed.
> If omitted, the value saved during `npm install -g` is used.
> You can change it at any time by re-running `qa-stlc init --integration <ado|jira|both>`.

---

## Requirements

- Node.js ≥ 18
- Python ≥ 3.10, < 3.14
- For **Azure DevOps** (Agents 1–4) — a `.env` containing:

```env
ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
ADO_PROJECT_NAME=YourProject
ADO_PAT=your-personal-access-token
APP_BASE_URL=your-app-base-url
APP_EMAIL=your-test-email@example.com
APP_PASSWORD=your-test-password
```

- For **Jira Cloud** (Agent 5) — additional `.env` vars:

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

See [Jira Authentication Setup](#jira-authentication-setup) for how to obtain these values.

---

## Commands

```bash
qa-stlc init [--vscode] [--python <path>] [--integration ado|jira|both]
# Full bootstrap: pip install + skills + agent files + MCP config
# Integration defaults to the value saved during npm install -g (prompted at that time)

qa-stlc scaffold [--name <name>] [--dir <path>] [--no-install]
# Copy full Playwright + Cucumber + TypeScript boilerplate to a new project directory

qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print]
# Copy skill files to the correct AI coding agent directory

qa-stlc mcp-config [--vscode] [--print] [--python <path>] [--playwright-port <n>]
# Write .vscode/mcp.json (--vscode) or .mcp.json (Claude Code)

qa-stlc verify
# Check that all six MCP servers are reachable
```

---

## Usage

Open your AI coding agent and use natural language:

```
# Azure DevOps — Generate test cases
Generate test cases for work item #12345 in MyProject at https://dev.azure.com/myorg

# Azure DevOps — Generate Gherkin BDD
Generate a Gherkin regression suite for Feature #11000 in MyProject at https://dev.azure.com/myorg

# Jira — Fetch issue and generate test cases
Generate test cases for Jira issue PROJ-123

# Jira — Fetch an Epic hierarchy
Fetch the full Epic hierarchy for PROJ-10 in Jira

# Generate Playwright code (requires Playwright MCP running — works with both ADO and Jira flows)
Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login

# Write to Helix-QA project
Write the generated files to my Helix-QA project at /workspace/my-qa-project
```

---

## Tool Reference

### qa-test-case-manager _(Azure DevOps)_

| Tool | Description |
|---|---|
| `fetch_work_item` | Fetch a PBI, Bug, or Feature with acceptance criteria, linked test cases, and coverage hints. Returns `epic_not_supported` for Epics. Returns `confirmation_required: true` for Features. |
| `get_linked_test_cases` | List all test cases already linked to a work item. Call before generating to power the deduplication diff. |
| `create_and_link_test_cases` | Create structured manual test cases in ADO and link them via TestedBy-Forward. |

### qa-gherkin-generator _(Azure DevOps)_

| Tool | Description |
|---|---|
| `fetch_feature_hierarchy` | Fetch a Feature and all child PBIs/Bugs with acceptance criteria and existing attachments. |
| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context, suggested file name, and linked test case steps. |
| `attach_gherkin_to_feature` | Validate and attach a `.feature` file to a Feature work item. |
| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file to a PBI or Bug work item. |
| `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |

### qa-playwright-generator _(ADO + Jira)_

| Tool | Description |
|---|---|
| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts`, and `cucumber-profile.js` from validated Gherkin + live AX-tree `context_map`. Hard-blocks if `context_map` is absent to prevent hallucinated locators. |
| `scaffold_locator_repository` | Generate the six Helix-QA healing infrastructure files. |
| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
| `attach_code_to_work_item` | Attach delta Playwright TypeScript files to an ADO work item. Pass only net-new delta files. |

### qa-helix-writer _(ADO + Jira)_

| 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 from the Helix-QA project for overlap detection. |
| `write_helix_files` | Write generated files to the correct Helix-QA paths. |

### qa-jira-manager _(Jira Cloud)_

| Tool | Description |
|---|---|
| `fetch_jira_issue` | Fetch a Story, Bug, or Task with acceptance criteria, coverage hints, and existing linked test case count. Returns `epic_use_hierarchy` for Epics. |
| `fetch_jira_epic_hierarchy` | Fetch an Epic with 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 an ADF table — no Xray required. Returns `confirmation_required: true` for Epics. |
| `get_linked_test_cases` | List all issues linked to a Jira issue via `is tested by` / `Test` link type. Call before generating to avoid duplicates. |

### 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. |
| `browser_file_upload` | Upload a file to a file input by ref. |

---

## MCP Config

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

```json
{
  "servers": {
    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
    "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-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}"
      }
    },
    "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
  }
}
```

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

```json
{
  "mcpServers": {
    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
    "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-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}"
      }
    },
    "playwright": { "type": "url", "url": "ws://localhost:8931" }
  }
}
```

> VS Code requires `http://localhost:8931/mcp` (with `/mcp` suffix).
> Claude Code requires `ws://localhost:8931` (WebSocket, no `/mcp`).
> `qa-stlc mcp-config` writes the correct format automatically.

---

## Skills Installed

Skills follow the [Agent Skills specification](https://agentskills.io/specification) and live under `skills/<n>/SKILL.md`.

| Skill | Purpose |
|---|---|
| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
| `generate-test-cases/SKILL.md` | PBI / Bug / Feature → ADO manual test cases |
| `generate-gherkin/SKILL.md` | Epic / Feature / PBI / Bug → validated `.feature` + ADO attach |
| `generate-playwright-code/SKILL.md` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
| `write-helix-files/SKILL.md` | Generated files → Helix-QA disk layout, scaffold or merge |
| `deduplication-protocol/SKILL.md` | READ → DIFF → CREATE mandatory pre-flight gate |
| `qa-jira-manager/SKILL.md` | Jira issue → test case issues + `is tested by` links |

> **Installed copies** (`.claude/skills/`, `.github/copilot-instructions/`) are generated by
> `qa-stlc init` / `qa-stlc skills` at project bootstrap time and are gitignored.
> The canonical source for all skills is the `skills/` directory.

---

## Jira Authentication Setup

`qa-jira-manager` uses **Jira OAuth 2.0 (3LO)** with a persistent file-based token cache
at `~/.jira-cache/jira-token.json` — the same silent-cache / browser-fallback pattern
used by the ADO MSAL auth module.

### 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**, enable: `read:jira-user`, `read:jira-work`, `write:jira-work`, `offline_access`
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 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

The browser opens once on startup. Sign in to Jira. The token is cached silently
and refreshed automatically for ~60 days — no re-prompting.

---

## Workflow Comparison: ADO vs Jira

| Step | Azure DevOps | Jira Cloud |
|---|---|---|
| Fetch issue | `fetch_work_item` | `fetch_jira_issue` |
| Fetch Epic hierarchy | ⛔ Not supported — warn user | ⛔ Not supported — warn user |
| Check for duplicates | `get_linked_test_cases` | `get_linked_test_cases` |
| Create & link test cases | `create_and_link_test_cases` | `create_and_link_test_cases` |
| Generate Gherkin | `fetch_work_item_for_gherkin` → `attach_gherkin_to_work_item` | `qa-gherkin-generator` with Jira issue AC (save locally or attach to Jira) |
| Generate Playwright | `generate_playwright_code` (shared) | `generate_playwright_code` (shared) |
| Write to disk | `write_helix_files` (shared) | `write_helix_files` (shared) |
| Authentication | MSAL silent + browser (`~/.msal-cache/`) | OAuth 2.0 (3LO) + browser (`~/.jira-cache/`) |
| Link relation | `TestedBy-Forward` | `is tested by` / `Test` link type |

---

## Three-Layer Self-Healing Architecture

| Layer | Class | What it heals |
|---|---|---|
| 1 — Locator | `LocatorHealer` | primary selector → role → label → text → AI Vision → CDPSession AX tree |
| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |

Healed selectors persist in `LocatorRepository`. HealingDashboard: `http://localhost:7890`.

All suggestions require human approval before entering version control.

---

## 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>

# Smoke only
cucumber-js --config=config/cucumber.js -p <feature_profile> --tags "@smoke"
```

---

## Scaffold a New QA Project

The `scaffold` command copies the full Playwright + Cucumber + TypeScript boilerplate framework — including three-layer AI self-healing, BDD templates, and CI/CD integration — into a new project directory.

```bash
# Scaffold into ./my-qa-project (default name)
qa-stlc scaffold

# Custom project name and location
qa-stlc scaffold --name acme-e2e --dir /path/to/workspace/acme-e2e

# Skip npm install (e.g. to inspect files first)
qa-stlc scaffold --name acme-e2e --no-install
```

After scaffolding:

```bash
cd my-qa-project
npx playwright install chromium     # install browser binaries
cp .env.example .env                # already done by scaffold
# Edit .env — set BASE_URL and optionally AI_API_KEY
npm test                            # run the example scenario
```

### What Gets Scaffolded

| Layer | Contents |
|---|---|
| **Config** | `package.json`, `tsconfig.json`, `cucumber.js`, `.env.example`, `.gitignore` |
| **CI/CD** | `Dockerfile`, `docker-compose.yml`, `azure-pipelines.yml` |
| **Framework** | `src/hooks/`, `src/pages/BasePage.ts`, `src/locators/`, `src/config/` |
| **Self-healing** | All healing utilities: `LocatorHealer`, `TimingHealer`, `VisualIntentChecker`, `HealingDashboard`, `review-server`, `healix-ci-apply`, etc. |
| **AI utilities** | `AILocatorGenerator`, `AISelfHealing`, `AITestGenerator` |
| **Auth** | `AuthManager`, `AuthSetup` |
| **Templates** | `_template.feature`, `_template.locators.ts`, `_template.steps.ts`, `_TemplatePage.ts` |
| **Example test** | `src/test/features/example.feature` + steps |

### Healing Dashboard

During a test run the live dashboard is available at **http://localhost:7890**. After the run use the review server for promote-to-source + PR creation:

```bash
npm run healix:review    # http://localhost:7891
# or in CI:
HEALIX_CI_AUTO_APPROVE=true npm run healix:apply-ci
```

---

## Development

```bash
# Install (all five agents from one pip package)
make install-ado         # install + ADO next steps
make install-jira        # install + Jira next steps
make install-both        # install + Both next steps

# Verify
make verify-ado          # ADO agents + MSAL auth cache
make verify-jira         # Jira agents + OAuth token cache
make verify-both         # all agents + both auth caches

# Skills
make skills-ado          # ADO skill files → .claude/skills/ + copilot-instructions/
make skills-jira         # Jira skill files
make skills-both         # all skill files

# MCP config
make mcp-config-ado      # write .mcp.json for ADO pipeline
make mcp-config-jira     # write .mcp.json for Jira pipeline
make mcp-config-both     # write .mcp.json for both pipelines

# Test + clean
make test                # run pytest tests/ -v
make clean               # remove .venv, __pycache__, dist
```

---

## 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)
- [Architecture Reference](docs/architecture.md)
- [End-to-End Walkthrough](docs/walkthrough.md)

---

## License

MIT