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

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

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

qa-stlc init
qa-stlc scaffold

This will perform the same setup steps as the postinstall script.

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

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
[email protected]
APP_PASSWORD=your-test-password

• For Jira Cloud (Agent 5) — additional .env vars:

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 for how to obtain these values.

Commands

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)

{
  "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)

{
  "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 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

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

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

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.

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

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:

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

Development

# 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
• Quick Start: Jira Cloud
• Architecture: ADO
• Architecture: Jira
• Walkthrough: ADO
• Walkthrough: Jira
• Architecture Reference
• End-to-End Walkthrough

License

MIT