@qa-gentic/stlc-agents 1.0.16 → 1.0.17

package/README.md

@@ -19,71 +19,60 @@ 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-gherkin-generator` | ADO or Jira Epic / Feature / PBI / Bug ID | `.feature` file attached to work item or saved locally |
+| `qa-playwright-generator` | Gherkin + live browser AX tree | `locators.ts` + page objects + step defs |
 | `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 |
+| `qa-jira-manager` | Jira Story / Bug / Task / Epic | Test cases in Jira + full pipeline to Helix-QA |
 
 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.
+> **ADO or Jira?** Both pipelines 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):
+# 2. Bootstrap your project
+qa-stlc init --vscode --integration ado    # GitHub Copilot / VS Code — ADO
+qa-stlc init --vscode --integration jira   # GitHub Copilot / VS Code — Jira
+qa-stlc init --vscode --integration both   # GitHub Copilot / VS Code — both
+# or for Claude Code:
 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)
+3. Copies custom agent files to `.github/agents/`
 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:
+| Requirement | Value |
+|---|---|
+| Node.js | >= 18 |
+| Python | >= 3.10, < 3.14 |
+| ADO PAT | Required for Agents 1–4 (ADO pipeline) |
+| Jira OAuth 2.0 (3LO) | Required for Agent 5 (Jira pipeline) |
+| Playwright MCP | `npx @playwright/mcp@latest --port 8931` |
+
+**ADO `.env` vars:**
 
 ```env
 ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
@@ -94,65 +83,25 @@ APP_EMAIL=your-test-email@example.com
 APP_PASSWORD=your-test-password
 ```
 
-- For **Jira Cloud** (Agent 5) — additional `.env` vars:
+**Jira `.env` vars (additional):**
 
 ```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
+## CLI 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
-```
+| Command | Description |
+|---|---|
+| `qa-stlc init [--vscode] [--integration ado\|jira\|both]` | Full bootstrap: pip install + skills + agent files + MCP config |
+| `qa-stlc scaffold [--name n] [--dir path]` | Copy full Playwright + Cucumber + TypeScript boilerplate to a new project |
+| `qa-stlc skills [--target claude\|vscode\|cursor\|windsurf]` | Copy skill files to the correct AI coding agent directory |
+| `qa-stlc mcp-config [--vscode] [--print]` | Write `.vscode/mcp.json` or `.mcp.json` with all servers configured |
+| `qa-stlc verify` | Check that all six MCP servers are reachable |
 
 ---
 
@@ -162,166 +111,58 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 
 | 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. |
+| `fetch_work_item` | Fetch a PBI, Bug, or Feature with acceptance criteria, coverage hints, and existing TC count. Returns `epic_not_supported` for Epics; `confirmation_required: true` for Features. |
+| `get_linked_test_cases` | List all test cases already linked to a work item (deduplication). |
+| `create_and_link_test_cases` | Create structured manual test cases in ADO and link 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. |
+| `fetch_feature_hierarchy` | Fetch a Feature and all child PBIs/Bugs with acceptance criteria and test case steps. |
+| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context and suggested file name. |
 | `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`. |
+| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file to a PBI or Bug. |
+| `validate_gherkin_content` | Structural validation — 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. |
+| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts`, and `cucumber-profile.js` from Gherkin + live AX-tree `context_map`. Hard-blocks if `context_map` is absent. |
+| `scaffold_locator_repository` | Generate the five 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. |
+| `attach_code_to_work_item` | Attach delta Playwright TypeScript files to an ADO work item. |
 
 ### 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. |
+| `list_helix_tree` | Full directory listing 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. |
 
 ### 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_issue` | Fetch a Story, Bug, or Task with acceptance criteria and coverage hints. 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.
+| `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. |
+| `get_linked_test_cases` | List all issues linked via `is tested by` / `Test` link type (deduplication). |
 
 ---
 
-## 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
-```
+## Three-Layer Self-Healing Architecture
 
-### Step 4 — First run
+| 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 |
 
-The browser opens once on startup. Sign in to Jira. The token is cached silently
-and refreshed automatically for ~60 days — no re-prompting.
+Healed selectors persist in `LocatorRepository`. All AI suggestions require human approval at `http://localhost:7890` before entering version control.
 
 ---
 
@@ -330,10 +171,10 @@ and refreshed automatically for ~60 days — no re-prompting.
 | Step | Azure DevOps | Jira Cloud |
 |---|---|---|
 | Fetch issue | `fetch_work_item` | `fetch_jira_issue` |
-| Fetch Epic hierarchy | ⛔ Not supported — warn user | ⛔ Not supported — warn user |
+| Fetch Epic hierarchy | Not supported — warn user | `fetch_jira_epic_hierarchy` |
 | 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 Gherkin | `fetch_work_item_for_gherkin` → `attach_gherkin_to_work_item` | `qa-gherkin-generator` with Jira AC |
 | 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/`) |
@@ -341,20 +182,6 @@ and refreshed automatically for ~60 days — no re-prompting.
 
 ---
 
-## 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
@@ -371,96 +198,14 @@ 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)
+- [ARCHITECTURE-ADO.md](ARCHITECTURE-ADO.md) — Full technical architecture, ADO pipeline
+- [ARCHITECTURE-JIRA.md](ARCHITECTURE-JIRA.md) — Full technical architecture, Jira pipeline
+- [WALKTHROUGH-ADO.md](WALKTHROUGH-ADO.md) — End-to-end walkthrough, ADO pipeline
+- [WALKTHROUGH-JIRA.md](WALKTHROUGH-JIRA.md) — End-to-end walkthrough, Jira pipeline
+- [PEER-DEV-PRESENTATION.md](PEER-DEV-PRESENTATION.md) — Developer team overview
+- [MANAGEMENT-ROI.md](MANAGEMENT-ROI.md) — ROI, quality impact, and cost analysis
 
 ---
 

package/bin/postinstall.js

@@ -84,7 +84,23 @@ if (!python) {
   }
 }
 
-// ── 3. Print next-step instructions ──────────────────────────────────────────
+// ── 3. Activate cost tracking on MCP servers ─────────────────────────────
+info("Activating cost tracking on MCP servers...");
+const costPatch = spawnSync(
+  python,
+  ["-m", "stlc_agents.shared.install_hook"],
+  { encoding: "utf8", stdio: "pipe" }
+);
+if (costPatch.status === 0) {
+  // Print each output line through our TTY writer
+  (costPatch.stdout || "").split("\n").filter(Boolean).forEach((l) => console.log(l));
+  ok("Cost tracking active — every tool call will log tokens + cost");
+} else {
+  warn("Cost tracking patch skipped (run manually: python -m stlc_agents.shared.install_hook)");
+  if (costPatch.stderr) console.log(d(costPatch.stderr.slice(0, 300)));
+}
+ 
+// ── 4. Print next-step instructions ──────────────────────────────────────────
 console.log(`
 ${b("Next steps")} — run these inside your project root:
 

package/bin/qa-stlc.js

@@ -22,6 +22,7 @@ const cmdSkills     = require("../src/cli/cmd-skills");
 const cmdMcpConfig  = require("../src/cli/cmd-mcp-config");
 const cmdVerify     = require("../src/cli/cmd-verify");
 const cmdScaffold   = require("../src/cli/cmd-scaffold");
+const cmdCost = require("../src/cli/cmd-cost");
 
 program
   .name("qa-stlc")
@@ -83,6 +84,28 @@ program
   .option("--no-install",  "Skip npm install after scaffolding")
   .action(cmdScaffold);
 
+  program
+  .command("cost")
+  .description(
+    "Show token usage and cost for stlc-agents pipeline sessions.\n" +
+    "Reads logs from ~/.qa-stlc/cost-*.jsonl written on every MCP tool call.\n\n" +
+    "Model detection order (first match wins):\n" +
+    "  1. STLC_CODING_AGENT_MODEL env var     (explicit override)\n" +
+    "  2. ANTHROPIC_MODEL env var             (set automatically by Claude Code)\n" +
+    "  3. GITHUB_COPILOT_MODEL env var        (set by Copilot if configured)\n" +
+    "  4. ~/.qa-stlc/agent-model file         (saved by --set-model)\n" +
+    "  5. claude-sonnet-4-6                   (default fallback)\n\n" +
+    "Claude Code users: no setup needed — model is detected automatically.\n" +
+    "Cursor / Windsurf users: run  qa-stlc cost --set-model <model-id>  once."
+  )
+  .option("--all",              "Show all sessions (default: last session only)")
+  .option("--session <id>",     "Show a specific session by ID")
+  .option("--json",             "Output raw JSON instead of a formatted table")
+  .option("--set-model <model>","Save your coding agent model for accurate pricing.\n" +
+    "                             e.g. claude-opus-4-6 | gpt-4o | claude-sonnet-4-6")
+  .option("--model-help",       "Explain model detection and all ways to configure it")
+  .action(cmdCost);
+  
 // ── Quick-start hint appended to every --help output ─────────────────────────
 program.addHelpText("after", `
 Quick Start (run once in your project root):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "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 Claude Code, GitHub Copilot, Cursor, Windsurf.",
   "keywords": [
     "playwright",

package/skills/write-helix-files/SKILL.md

@@ -47,6 +47,12 @@ When(/^the user enters "([^"]*)" in the username field$/, async function (value:
 If `generate_playwright_code` produced regex patterns, use `pre_validate_cucumber_steps`
 to identify them, then convert to Cucumber expressions before calling `write_helix_files`.
 
+**HARD STOP 4 — Cucumber config: append only, never create.**
+If any Cucumber config file exists (`src/config/cucumber.config.ts` or project-root
+`cucumber.js`), only append new profiles—never create a new file.
+`write_helix_files` will automatically skip profile creation if the file does not
+exist, to prevent orphaned config files from being left behind.
+
 ---
 
 Place files produced by `qa-playwright-generator` into a local Helix-QA