# @qa-gentic/stlc-agents — Azure DevOps Quick Start

> Azure DevOps pipeline: work item → test cases → Gherkin → Playwright TypeScript → Helix-QA.
> For Jira Cloud see [QUICKSTART-JIRA.md](QUICKSTART-JIRA.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)
[![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

Six Python MCP servers cover the full QA Software Test Life Cycle. The ADO pipeline uses Agents 1–4 + the migration tool:

| Agent | Input | Output |
|---|---|---|
| `qa-test-case-manager` | ADO PBI / Bug / Feature ID | Manual test cases created & linked via TestedBy-Forward |
| `qa-gherkin-generator` | ADO Feature / PBI / Bug ID | `.feature` file attached to the ADO work item |
| `qa-playwright-generator` | Gherkin + live browser | `locators.ts` + page objects + step defs attached to ADO |
| `qa-helix-writer` | Generated `.ts` files + `helix_root` | Files written to Helix-QA directory layout on disk |
| `qa-migration` / `stlc-migrate` | Existing Playwright project | Fully agent-ready Helix-QA tree — healer scaffold + skills + `.mcp.json` + 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

### Greenfield (new Playwright + Cucumber + TypeScript project)

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

`qa-stlc init` performs:
1. `pip install qa-gentic-stlc-agents` — installs all six Python MCP servers + `stlc-migrate` CLI
2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
3. Writes `.vscode/mcp.json` with all six servers configured (Agents 1–4 + `qa-migration` + `playwright`)

Start the Playwright MCP server before your first session:

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

### Migrating an existing Playwright project

```bash
# Preview what would land in the target tree (writes nothing)
stlc-migrate --source ./my-old-tests --helix ./helix-qa --dry-run

# Full migration — installs every ADO agent skill + .mcp.json + healer scaffold
stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado

# Refresh an already-migrated tree (picks up tool-side scaffold improvements,
# and auto-removes stale orphans from src/test/features|steps and src/pages|locators)
stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado --conflict overwrite

# Mirror the source's subfolder grouping under features/steps/pages/locators
# (default flattens everything; sub-dir names are kebab-cased)
stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado --preserve-tree

# Explicitly scaffold VRT (visual regression testing). Auto-enabled when the
# source already uses vrt:* npm scripts or VRT_MODE in any .env file.
stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado --features=vrt
```

After migration:

```bash
cd ./helix-qa
npm install              # picks up dotenv, @types/fs-extra, etc.
npx tsc --noEmit         # should be clean (any errors are source bugs preserved verbatim)
npm test                 # healing fires on broken primary selectors and writes self-heals/healed-locators[.<env>].json
npm run healix:dashboard # http://localhost:7890 — Confirm / Revert healed locators
npm run healix:review    # http://localhost:7891 — read-only mirror (set HEALIX_REVIEW_PORT to enable)
```

See `skills/migrate-framework/SKILL.md` for the full migration pipeline + every healing env var.

---


## Requirements

- Node.js ≥ 18
- Python ≥ 3.10, < 3.14
- Azure DevOps organisation with 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
```

---

## Commands


```bash
qa-stlc init [--vscode] [--python <path>] [--integration ado|jira|both]
# Full bootstrap: pip install + skills + MCP config

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

stlc-migrate --source <existing> --helix <target> [--integration ado|jira|both] [--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. Installs every agent skill, .mcp.json, healer scaffold,
# AGENT-BEHAVIOR.md, ORCHESTRATION_RULES.md, and the 11-file BOILERPLATE
# allowlist (strategy / rules / apply / helpers / config). The enhanced
# `LocatorHealer` / `LocatorRepository` / `TimingHealer` / `VisualIntentChecker`
# / `HealingDashboard` / `dashboard-server` scaffolds always win over BOILERPLATE
# on overlapping files (schema v1, debounced persist, dashboard write-back).
```

### Makefile shortcuts

```bash
make bootstrap-ado                                       # one-shot: skills + .mcp.json for the ADO pipeline
make migrate-ado SOURCE=<old> HELIX=<new>                # ADO migration with sensible defaults
make migrate-ado 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:

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

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

# Generate Playwright code (requires Playwright MCP running)
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

| 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

| 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

| 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

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

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

> For ADO-only installs `qa-jira-manager` is omitted. Run `qa-stlc mcp-config --integration ado` to generate manually, or run `stlc-migrate --integration ado` and the migration will emit `.mcp.json` automatically with absolute binary paths.

### 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-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
    "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-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--isolated"] }
  }
}
```

> 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

| Skill | Purpose |
|---|---|
| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
| `generate-test-cases/` | PBI / Bug / Feature → ADO manual test cases (ADO only) |
| `generate-gherkin/` | Feature / PBI / Bug → validated `.feature` + ADO attach |
| `generate-playwright-code/` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
| `write-helix-files/` | Generated files → Helix-QA disk layout, scaffold or merge |
| `deduplication-protocol/` | READ → DIFF → CREATE mandatory pre-flight gate |

---


## Three-Layer Self-Healing Architecture

| 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.) — never the search union. The attribute strategy constrains substring matches by intent shape so `"password input"` only resolves to real `<input>` elements, never `<a id="forgot-password">`. |
| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |

Healed selectors persist in `LocatorRepository` under a schema-v1 envelope at
`self-heals/healed-locators[.<ENV>].json` (heal-only filter, debounced writes,
read-modify-write merge, history cap). `HEAL_STRATEGY_ORDER` reorders the chain
at class-load time; `LOCATOR_HEAL_ATTEMPTS` caps strategy retries; `LOCATOR_TIMEOUT`
caps each `ATTACH_TO` probe.

**HealingDashboard** runs as two servers from the same process:
- `http://localhost:7890` — read/write: Confirm rewrites the source `*.locators.ts` `selector:` field; Revert restores the previous selector.
- `http://localhost:7891` — read-only mirror (set `HEALIX_REVIEW_PORT` to enable).

All Confirm actions persist to the source locator file in version control. Refer to
[ARCHITECTURE-ADO.md § Three-Layer Self-Healing Architecture](ARCHITECTURE-ADO.md#three-layer-self-healing-architecture)
for full env-var tuning and the write-back protocol.

---

## 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** | `LocatorHealer` (8-strategy chain), `LocatorRepository` (schema v1 envelope, heal-only filter), `TimingHealer`, `VisualIntentChecker`, `HealingDashboard` (write-back to source), `dashboard-server` (launcher for `npm run healix:dashboard` / `healix:review`). |
| **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

`npm run healix:dashboard` launches a single process that serves both:

```bash
npm run healix:dashboard          # http://localhost:7890 — Confirm / Revert (rewrites source *.locators.ts)
HEALIX_REVIEW_PORT=7891 npm run healix:dashboard   # also serves http://localhost:7891 read-only mirror
```

Confirm on any healed entry writes the persisted single-attribute selector back to
the source `*.locators.ts` `selector:` field in version control — no separate
"promote to source" or CI step required.

---


## Development

```bash
make install-ado      # create .venv + pip install -e . (prints ADO next steps)
make install-jira     # create .venv + pip install -e . (prints Jira next steps)
make install-both     # create .venv + pip install -e . (prints Both next steps)
make test             # run pytest tests/ -v
make skills-ado       # install ADO skill files to .claude/skills/ + copilot-instructions/
make skills-jira      # install Jira skill files
make skills-both      # install all skill files
make verify-ado       # check ADO agents + MSAL auth
make verify-jira      # check Jira agents + OAuth token cache
make mcp-config-ado   # write .vscode/mcp.json for ADO pipeline
make mcp-config-jira  # write .vscode/mcp.json for Jira pipeline
make mcp-config-both  # write .vscode/mcp.json for both pipelines
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)

---


## License

MIT