@qa-gentic/stlc-agents 1.0.14 → 1.0.16

package/README.md

@@ -170,7 +170,6 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 
 | Tool | Description |
 |---|---|
-| `fetch_epic_hierarchy` | Fetch an Epic and all child Features, PBIs, Bugs, and existing test cases. |
 | `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. |
@@ -331,7 +330,7 @@ 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 | `fetch_epic_hierarchy` | `fetch_jira_epic_hierarchy` |
+| 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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "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/AGENT-BEHAVIOR.md

@@ -229,25 +229,18 @@ OUTPUT: .feature file attached to PBI/Bug work item (or shown inline)
 ```
 INPUT:  Epic ID  +  org URL  +  project name
   │
-  ├─ fetch_epic_hierarchy(id)
-  │    └─ returns: features[] each with child_work_items[] and existing_test_cases[]
-  │
-  ├─ [read ALL child Features and ALL child PBIs/Bugs before writing any Gherkin]
-  │
-  ├─ for each child Feature:
-  │    ├─ [deduplication-protocol Phase 1+2 for that Feature ID]
-  │    ├─ [gap check for that Feature]
-  │    ├─ [live snapshots for that Feature's screens]
-  │    ├─ generate .feature file (5–10 scenarios)
-  │    ├─ validate_gherkin_content(scope="feature")
-  │    ├─ [show content to user]
-  │    ├─ [ASK: "Attach .feature to Feature #{child_id}?"]
-  │    └─ yes  →  attach_gherkin_to_feature(child_id)
-  │
-  └─ [NEVER call create_and_link_test_cases on the Epic ID]
-
-OUTPUT: one .feature file per child Feature
-        test cases NOT created unless user explicitly asks for child Feature/PBI coverage
+  └─ DO NOT call any fetch tool.
+     Respond immediately with:
+       "Epic-scoped Gherkin generation is not supported. An Epic spans multiple Features
+        and would produce files that are too large and unfocused to be useful.
+
+        Please provide one of the following instead:
+          • A Feature ID — I will generate 5–10 scenarios covering all child PBIs
+          • A PBI or Bug ID — I will generate 3–9 scenarios scoped to that work item
+
+        To find the child Features under this Epic, look up the work item in Azure DevOps
+        and note the Feature IDs, then share them with me."
+     Wait for the user to provide a Feature or PBI/Bug ID. Do not proceed.
 ```
 
 ### Chain E — Playwright TypeScript from Gherkin
@@ -322,7 +315,7 @@ User provides work item ID
          │
          ▼
   Call the fetch tool for the intended operation
-  (fetch_work_item, fetch_work_item_for_gherkin, or fetch_epic_hierarchy)
+  (fetch_work_item or fetch_work_item_for_gherkin)
          │
          ▼
   Read work_item_type from response
@@ -332,8 +325,8 @@ User provides work item ID
   "Epic"                                          not "Epic"
     │                                                  │
     ▼                                            ┌─────┴────────┐
-  HARD STOP for test cases                    "Feature"    "PBI"/"Bug"
-  Use fetch_epic_hierarchy for Gherkin            │              │
+  HARD STOP — warn user to provide            "Feature"    "PBI"/"Bug"
+  a Feature or PBI/Bug ID instead                │              │
   Never call create_and_link_test_cases           │              │
   Never call attach_code_to_work_item             │              │
   on the Epic ID                             Feature path   PBI/Bug path

package/skills/deduplication-protocol/SKILL.md

@@ -122,6 +122,53 @@ From the feature hierarchy response, check for:
 > If you cannot read an attachment's content, treat it as fully covering its domain and
 > produce NO new file of that type unless you can prove a gap.
 
+### 1E — Helix step-pattern scan (mandatory before generating any step definitions)
+
+ADO attachments only cover files explicitly uploaded. The Helix-QA project on disk contains
+all currently registered step definitions — many of which are **never attached to ADO** but
+will be active at runtime because `cucumber.js` loads them via `src/test/steps/**/*.ts`.
+
+Generating a new step that duplicates an existing Helix step causes an
+`Ambiguous step definition` runtime error, even if the ADO dedup scan found nothing.
+
+**Procedure — run every time before writing any `*.steps.ts`:**
+
+```
+1. qa-helix-writer:list_helix_tree(helix_root)
+   → collect all paths matching src/test/steps/*.steps.ts
+
+2. For each path found:
+   qa-helix-writer:read_helix_file(helix_root, path)
+   → extract all step pattern strings (Given/When/Then/And/But)
+   → extract all Before/After hook tags
+   → add to CACHE[id].existing_attachments.steps_files[]
+
+3. For each path matching src/test/features/*.feature:
+   qa-helix-writer:read_helix_file(helix_root, path)
+   → extract the Background step strings verbatim
+   → add to CACHE[id].existing_attachments.background_steps[]
+```
+
+**Background reuse rule:** If a Background in a new feature file can be expressed entirely
+using step patterns already registered in any existing `*.steps.ts`, you **must** use the
+exact registered wording — do NOT generate new step strings for the same intent.
+
+```
+# ✅ Correct — reuses registered pattern from reset-app-state.steps.ts
+Background:
+  Given the user is logged in as "standard_user"
+  And the user is on the inventory page
+
+# ❌ Wrong — generates duplicate steps that cause Ambiguous step definition
+Background:
+  Given I am on the SauceDemo login page at "https://www.saucedemo.com/"
+  And I log in with username "standard_user" and password "secret_sauce"
+  And I am on the inventory page at "https://www.saucedemo.com/inventory.html"
+```
+
+> This scan is **not optional for Jira pipelines either**. If the Helix project is present,
+> always perform step 1E before writing steps, regardless of the work item source.
+
 ---
 
 ## PHASE 2 — DIFF Using Semantic Matching
@@ -163,7 +210,7 @@ For each proposed Gherkin scenario:
 
 - `locators.ts`: only emit keys not already in existing file; if delta empty → skip; if non-empty → attach as `locators.delta.ts`
 - `*Page.ts`: only emit methods not already present; if delta empty → skip; if non-empty → attach as `*Page.delta.ts`
-- `*.steps.ts`: only emit step strings not already registered; NEVER re-register an existing step (causes `Ambiguous step definition` runtime error)
+- `*.steps.ts`: cross-check every proposed step pattern against **both** ADO attachment step strings (1D) **and** Helix on-disk step strings (1E); only emit step strings that appear in neither; NEVER re-register an existing step (causes `Ambiguous step definition` runtime error); reuse exact registered wording in Background blocks
 
 ---
 
@@ -211,7 +258,7 @@ Output after every run regardless of whether anything was created:
 
 1. **NEVER call `create_and_link_test_cases` without first calling `get_linked_test_cases`** on the same work item.
 2. **NEVER attach a `.feature` file without first checking for existing feature file attachments.**
-3. **NEVER attach a `steps.ts` that re-registers an existing step string** — causes `Ambiguous step definition` at runtime.
+3. **NEVER attach a `steps.ts` that re-registers an existing step string** — causes `Ambiguous step definition` at runtime. Perform the Helix step-pattern scan (Phase 1E) before writing any step definition. ADO attachment checks alone are insufficient because most Helix step files are never attached to ADO.
 4. **NEVER treat tag differences as meaningful.** `[REGRESSION] Export List downloads CSV` is a duplicate of `[SMOKE] Clicking Export List downloads a valid CSV file`.
 5. **NEVER create more than one test case covering the same (subject, condition) pair.**
 6. **NEVER skip this protocol because the work item appears new.** `existing_test_cases_count: 0` in the hierarchy can still have cases via `get_linked_test_cases` — always call both.
@@ -252,7 +299,8 @@ CACHE[work_item_id] = {
     feature_files: [{ name, content }],
     locators_ts:   { found: bool, keys: [] },
     page_objects:  [{ name, methods: [] }],
-    steps_files:   [{ name, step_strings: [] }],
+    steps_files:   [{ name, step_strings: [] }],   # populated from BOTH 1D (ADO attachments) AND 1E (Helix on-disk read)
+    background_steps: [],                               # exact step strings from existing Helix *.feature Background blocks — new Backgrounds must reuse these
   },
   gap_check_completed:  bool,   # set true after generate-gherkin Step 2 passes
   phase1_completed:     true,

package/skills/generate-gherkin/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use when generating Gherkin feature files, BDD scenarios, or .feature files from Azure DevOps
   or Jira work items. Triggers on: "Gherkin", "feature file", "BDD", "scenarios", "acceptance
   criteria automation", "Given When Then", "regression suite". Enforces live navigation before
-  writing any scenario and links generated files back to work items. Works with Epic, Feature,
+  writing any scenario and links generated files back to work items. Works with Feature,
   PBI, and Bug work item types.
 license: MIT
 compatibility: "Requires qa-gherkin-generator, qa-playwright-generator, qa-test-case-manager MCP servers and Playwright MCP running at localhost:8931 for live locator verification."
@@ -60,7 +60,7 @@ work items in ADO.**
 
 | ID type given by user | Goal | Fetch tool | Attach tool | Scope |
 |---|---|---|---|---|
-| **Epic ID** | Full regression suite across ALL child Features and their PBIs/Bugs | `fetch_epic_hierarchy` | `attach_gherkin_to_feature` (once per child Feature) | 5–10 scenarios per Feature |
+| **Epic ID** | ⛔ Not supported — warn user | — | — | — |
 | **Feature ID** | Full regression suite across all child PBIs | `fetch_feature_hierarchy` | `attach_gherkin_to_feature` | 5–10 scenarios |
 | **PBI or Bug ID** | Scoped file for that single story in the current sprint | `fetch_work_item_for_gherkin` | `attach_gherkin_to_work_item` | 3–9 scenarios |
 
@@ -68,15 +68,19 @@ work items in ADO.**
 
 ```
 if user_input contains an Epic ID:
-    → ALWAYS use fetch_epic_hierarchy  (never fall through to fetch_feature_hierarchy)
-    → fetch_epic_hierarchy returns ALL child Features, their PBIs/Bugs, and all linked TCs
-    → analyse every Feature and every child PBI/Bug before generating any Gherkin
-    → generate one .feature file per child Feature (5–10 scenarios each)
-    → attach each via attach_gherkin_to_feature on the respective Feature ID
-    → DO NOT create manual test cases (create_and_link_test_cases) for the Epic itself
-      → inform the user: "Test cases cannot be created for an Epic. They can only be
-        created for PBIs, Bugs, or Features. Would you like me to create test cases for
-        the individual child Features or PBIs instead?"
+    → DO NOT call any fetch tool.
+    → Respond immediately with:
+      "Epic-scoped Gherkin generation is not supported. An Epic spans multiple Features
+       and would produce files that are too large and unfocused to be useful as a
+       regression suite.
+
+       Please provide one of the following instead:
+         • A Feature ID — I will generate 5–10 scenarios covering all child PBIs
+         • A PBI or Bug ID — I will generate 3–9 scenarios scoped to that work item
+
+       To find the child Features under this Epic, look up the work item in Azure DevOps
+       and note the Feature IDs, then share them with me."
+    → Wait for the user to provide a Feature or PBI/Bug ID. Do not proceed.
 
 if user_input contains a Feature ID:
     → use fetch_feature_hierarchy  +  attach_gherkin_to_feature
@@ -93,12 +97,6 @@ if ambiguous (no ID, just a title or description):
     → do not guess or default to either path
 ```
 
-When using the **Epic path**, `fetch_epic_hierarchy` returns a `features` list where each
-entry contains the Feature's metadata plus its `child_work_items` (PBIs/Bugs) and
-`existing_test_cases`. **Read every Feature and every child PBI/Bug in this list** before
-writing a single scenario — the full cross-Feature flow is the only correct input for an
-Epic-scope suite.
-
 When using the **PBI/Bug path**, `fetch_work_item_for_gherkin` returns `parent_feature`
 metadata. Use it for context when writing scenarios — but the generated file covers **only
 the PBI/Bug's own acceptance criteria**, not the full Feature. The file is attached to the
@@ -153,19 +151,6 @@ A single work item never tells the whole story.
 
 **1A — Route to the correct fetch tool (see Tool Routing above):**
 
-*Epic path (ALWAYS use when an Epic ID is provided):*
-```
-qa-gherkin-generator:fetch_epic_hierarchy(
-  epic_id          : <Epic ID>
-  organization_url : ...
-  project_name     : ...
-)
-```
-Extract: epic title/description, **all child Features**, each Feature's child PBIs/Bugs
-with their ACs, and all existing test cases. Analyse the ENTIRE hierarchy — every Feature
-and every PBI/Bug — before writing a single scenario. Generate one .feature file per
-child Feature.
-
 *Feature path:*
 ```
 qa-gherkin-generator:fetch_feature_hierarchy(

package/skills/generate-gherkin/references/step-by-step.md

@@ -197,15 +197,11 @@ that document — do not carry over the Gherkin attachment confirmation.
 
 ## Quality Gates — Do Not Attach Without These
 
-- [ ] Work item type identified — **correct tool-routing path selected** (Epic vs Feature vs PBI/Bug)
-- [ ] **Epic path**: `fetch_epic_hierarchy` called — NOT `fetch_feature_hierarchy` or `fetch_work_item_for_gherkin`
-- [ ] **Epic path**: ALL child Features and ALL child PBIs/Bugs read and analysed before any Gherkin written
-- [ ] **Epic path**: One .feature file generated per child Feature (not one file for the whole Epic)
-- [ ] **Epic path**: `create_and_link_test_cases` NOT called on the Epic ID — user informed that test cases are scoped to Features/PBIs/Bugs only
+- [ ] Work item type identified — **correct tool-routing path selected** (Feature vs PBI/Bug)
 - [ ] **Feature path**: `fetch_feature_hierarchy` called — all child PBIs/Bugs reviewed
 - [ ] **Feature path**: User confirmation received before calling `create_and_link_test_cases`
 - [ ] **PBI/Bug path**: `fetch_work_item_for_gherkin` called — parent Feature context reviewed
-- [ ] Correct fetch tool called: `fetch_epic_hierarchy` for Epic, `fetch_feature_hierarchy` for Feature, `fetch_work_item_for_gherkin` for PBI/Bug
+- [ ] Correct fetch tool called: `fetch_feature_hierarchy` for Feature, `fetch_work_item_for_gherkin` for PBI/Bug
 - [ ] Parent Feature hierarchy context reviewed — all active sibling PBIs/Bugs read and flow map built
 - [ ] Gap check (Step 2) completed — every G1–G7 gap type checked
 - [ ] **All gaps answered by user before any Gherkin was written** (or explicit sign-off obtained)

package/skills/generate-playwright-code/SKILL.md

@@ -218,7 +218,15 @@ qa-playwright-generator:generate_playwright_code(
 )
 ```
 
-The tool produces four files:
+The response contains `cache_key`, `files_manifest` (list of file paths), and `validation`. File
+contents are held server-side to keep them out of conversation history. Retrieve them only when
+you are about to attach or write to disk:
+
+```
+qa-playwright-generator:get_generated_files(cache_key: "<cache_key from above>")
+```
+
+The four generated files are:
 - `locators.ts` — selector registry with intent, stability score, visualIntent flag
 - `{ScreenName}Page.ts` — three-layer self-healing page object
 - `{feature}.steps.ts` — Cucumber step definitions
@@ -264,17 +272,21 @@ Note:
 
 **Do not call `attach_code_to_work_item` until the user replies "yes".**
 
-If user says "yes", call with delta files only:
+If user says "yes", first retrieve the file contents then attach:
 
 ```
+# 1 — Retrieve file contents from cache
+qa-playwright-generator:get_generated_files(cache_key: "<cache_key>")
+
+# 2 — Attach delta files only
 qa-playwright-generator:attach_code_to_work_item(
   organization_url : "<org_url>",
   project_name     : "<project>",
   work_item_id     : <id>,
   files            : [
-    { file_name: "locators.delta.ts",         content: "..." },
-    { file_name: "{ScreenName}Page.delta.ts",  content: "..." },
-    { file_name: "{feature}.steps.delta.ts",   content: "..." }
+    { file_name: "locators.delta.ts",         content: "<from get_generated_files>" },
+    { file_name: "{ScreenName}Page.delta.ts",  content: "<from get_generated_files>" },
+    { file_name: "{feature}.steps.delta.ts",   content: "<from get_generated_files>" }
   ]
 )
 ```
@@ -289,123 +301,8 @@ Helix-QA disk writes are a separate decision requiring a separate user request.
 
 ## Generated File Structures
 
-### locators.ts
-
-```typescript
-/**
- * Locators: <ScreenName>Page
- * SOURCE: Playwright MCP AX tree snapshot — <app-url>/<route>
- * Stability: data-testid(100) > role+name(90) > id(80) > aria-label(70) > placeholder(60)
- * ⚠ stability:0 entries were NOT reached in the live session — get user sign-off before using.
- */
-export const <ScreenName>Locators = {
-  // stability: 100 — data-testid, survives refactors
-  addUsersButton: {
-    selector  : "[data-testid='person_header-button-add_users']",
-    intent    : "Add Users button that opens the slide-out panel",
-    stability : 100,
-  },
-  // stability: 90 — aria-role+name, visualIntent: screenshot at assertions
-  exportListButton: {
-    selector     : "button:has-text('Export List')",
-    intent       : "Export List button on the failure summary screen",
-    stability    : 90,
-    visualIntent : true,
-  },
-  // ⚠ stability: 0 — NOT VERIFIED: could not reach this screen (reason: <why>)
-  // Get user sign-off before using in automation.
-  someUnreachedElement: {
-    selector  : "[data-testid='TODO']",
-    intent    : "...",
-    stability : 0,
-  },
-} as const;
-
-export type LocatorKey = keyof typeof <ScreenName>Locators;
-```
-
-### {ScreenName}Page.ts
-
-```typescript
-import { Page, expect, Download } from '@playwright/test';
-import { fixture }               from '@hooks/pageFixture';
-import { <ScreenName>Locators }  from './locators';
-import { LocatorHealer }         from '@utils/locators/LocatorHealer';
-import { LocatorRepository }     from '@utils/locators/LocatorRepository';
-import { VisualIntentChecker }   from '@utils/locators/VisualIntentChecker';
-import { TimingHealer }          from '@utils/locators/TimingHealer';
-
-/**
- * <ScreenName>Page — Three-Layer Self-Healing Page Object
- * Layer 1 (LocatorHealer):  primary → role → label → text → AI Vision → AX tree
- * Layer 2 (TimingHealer):   network-trace drift → auto-adjusted timeouts
- * Layer 3 (VisualIntentChecker): element screenshot diff at key assertions
- * HealingDashboard: http://localhost:7890
- * RULE: Never use page.click / page.fill / page.locator directly.
- */
-export default class <ScreenName>Page {
-  private readonly loc    = <ScreenName>Locators;
-  private readonly page:   Page;
-  private readonly healer: LocatorHealer;
-  private readonly repo:   LocatorRepository;
-  private readonly visual: VisualIntentChecker;
-  private readonly timing: TimingHealer;
-
-  constructor(page?: Page) {
-    this.page   = page ?? fixture().page;
-    this.repo   = fixture().locatorRepository ?? new LocatorRepository();
-    this.healer = new LocatorHealer(this.page, fixture().logger, this.repo);
-    this.visual = new VisualIntentChecker(this.page, fixture().logger, this.repo);
-    this.timing = new TimingHealer(this.page, fixture().logger, this.repo);
-    Object.entries(this.loc).forEach(([k, v]) => this.repo.register(k, v.selector, v.intent));
-  }
-
-  async login(email: string, password: string): Promise<void> {
-    await this.page.goto(process.env.APP_BASE_URL!, { waitUntil: 'networkidle' });
-    await this.healer.fillWithHealing('emailInput',    this.loc.emailInput.selector,    email,    this.loc.emailInput.intent);
-    await this.healer.fillWithHealing('passwordInput', this.loc.passwordInput.selector, password, this.loc.passwordInput.intent);
-    await this.healer.clickWithHealing('loginButton',  this.loc.loginButton.selector,             this.loc.loginButton.intent);
-    await this.timing.waitForNetworkIdle('login');
-  }
-
-  // All interactions go through LocatorHealer — never raw page.click / page.fill
-}
-```
-
-### {feature}.steps.ts
-
-```typescript
-import { Given, When, Then, Before } from '@cucumber/cucumber';
-import { expect }                    from '@playwright/test';
-import { fixture }                   from '@hooks/pageFixture';
-import <ScreenName>Page              from '@pages/<screenName>/<ScreenName>Page';
-
-let page_: <ScreenName>Page;
-
-Before(async () => { page_ = new <ScreenName>Page(fixture().page); });
-
-Given('I am logged in to {word} as {string}', async (_app: string, email: string) => {
-  await page_.login(email, process.env.APP_PASSWORD!);
-});
-
-// Only net-new steps — never re-register steps already in existing files
-```
-
----
-
-## Run Commands
-
-```bash
-ENABLE_SELF_HEALING=true \
-HEALING_DASHBOARD_PORT=7890 \
-APP_BASE_URL=https://account.myamplify.io \
-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"
-```
+For TypeScript code templates and run commands, see
+[references/file-structures.md](references/file-structures.md).
 
 ---
 

package/skills/generate-playwright-code/references/file-structures.md

@@ -0,0 +1,128 @@
+# Generated File Structures — Reference
+
+Read this file when you need to understand the exact TypeScript output format or
+run commands. It is not loaded into context automatically.
+
+---
+
+## locators.ts
+
+```typescript
+/**
+ * Locators: <ScreenName>Page
+ * SOURCE: Playwright MCP AX tree snapshot — <app-url>/<route>
+ * Stability: data-testid(100) > role+name(90) > id(80) > aria-label(70) > placeholder(60)
+ * ⚠ stability:0 entries were NOT reached in the live session — get user sign-off before using.
+ */
+export const <ScreenName>Locators = {
+  // stability: 100 — data-testid, survives refactors
+  addUsersButton: {
+    selector  : "[data-testid='person_header-button-add_users']",
+    intent    : "Add Users button that opens the slide-out panel",
+    stability : 100,
+  },
+  // stability: 90 — aria-role+name, visualIntent: screenshot at assertions
+  exportListButton: {
+    selector     : "button:has-text('Export List')",
+    intent       : "Export List button on the failure summary screen",
+    stability    : 90,
+    visualIntent : true,
+  },
+  // ⚠ stability: 0 — NOT VERIFIED: could not reach this screen (reason: <why>)
+  // Get user sign-off before using in automation.
+  someUnreachedElement: {
+    selector  : "[data-testid='TODO']",
+    intent    : "...",
+    stability : 0,
+  },
+} as const;
+
+export type LocatorKey = keyof typeof <ScreenName>Locators;
+```
+
+---
+
+## {ScreenName}Page.ts
+
+```typescript
+import { Page, expect, Download } from '@playwright/test';
+import { fixture }               from '@hooks/pageFixture';
+import { <ScreenName>Locators }  from './locators';
+import { LocatorHealer }         from '@utils/locators/LocatorHealer';
+import { LocatorRepository }     from '@utils/locators/LocatorRepository';
+import { VisualIntentChecker }   from '@utils/locators/VisualIntentChecker';
+import { TimingHealer }          from '@utils/locators/TimingHealer';
+
+/**
+ * <ScreenName>Page — Three-Layer Self-Healing Page Object
+ * Layer 1 (LocatorHealer):  primary → role → label → text → AI Vision → AX tree
+ * Layer 2 (TimingHealer):   network-trace drift → auto-adjusted timeouts
+ * Layer 3 (VisualIntentChecker): element screenshot diff at key assertions
+ * HealingDashboard: http://localhost:7890
+ * RULE: Never use page.click / page.fill / page.locator directly.
+ */
+export default class <ScreenName>Page {
+  private readonly loc    = <ScreenName>Locators;
+  private readonly page:   Page;
+  private readonly healer: LocatorHealer;
+  private readonly repo:   LocatorRepository;
+  private readonly visual: VisualIntentChecker;
+  private readonly timing: TimingHealer;
+
+  constructor(page?: Page) {
+    this.page   = page ?? fixture().page;
+    this.repo   = fixture().locatorRepository ?? new LocatorRepository();
+    this.healer = new LocatorHealer(this.page, fixture().logger, this.repo);
+    this.visual = new VisualIntentChecker(this.page, fixture().logger, this.repo);
+    this.timing = new TimingHealer(this.page, fixture().logger, this.repo);
+    Object.entries(this.loc).forEach(([k, v]) => this.repo.register(k, v.selector, v.intent));
+  }
+
+  async login(email: string, password: string): Promise<void> {
+    await this.page.goto(process.env.APP_BASE_URL!, { waitUntil: 'networkidle' });
+    await this.healer.fillWithHealing('emailInput',    this.loc.emailInput.selector,    email,    this.loc.emailInput.intent);
+    await this.healer.fillWithHealing('passwordInput', this.loc.passwordInput.selector, password, this.loc.passwordInput.intent);
+    await this.healer.clickWithHealing('loginButton',  this.loc.loginButton.selector,             this.loc.loginButton.intent);
+    await this.timing.waitForNetworkIdle('login');
+  }
+
+  // All interactions go through LocatorHealer — never raw page.click / page.fill
+}
+```
+
+---
+
+## {feature}.steps.ts
+
+```typescript
+import { Given, When, Then, Before } from '@cucumber/cucumber';
+import { expect }                    from '@playwright/test';
+import { fixture }                   from '@hooks/pageFixture';
+import <ScreenName>Page              from '@pages/<screenName>/<ScreenName>Page';
+
+let page_: <ScreenName>Page;
+
+Before(async () => { page_ = new <ScreenName>Page(fixture().page); });
+
+Given('I am logged in to {word} as {string}', async (_app: string, email: string) => {
+  await page_.login(email, process.env.APP_PASSWORD!);
+});
+
+// Only net-new steps — never re-register steps already in existing files
+```
+
+---
+
+## Run Commands
+
+```bash
+ENABLE_SELF_HEALING=true \
+HEALING_DASHBOARD_PORT=7890 \
+APP_BASE_URL=https://account.myamplify.io \
+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"
+```

package/skills/generate-test-cases/SKILL.md

@@ -35,8 +35,8 @@ If the user provides an Epic ID and asks for test cases:
 - Inform the user explicitly:
   > "Manual test cases cannot be created or linked to an Epic in ADO.
   > Test cases must be attached to individual Features, PBIs, or Bugs.
-  > Would you like me to use `fetch_epic_hierarchy` to identify the child Features
-  > and PBIs/Bugs, then create test cases for those instead?"
+  > Please look up the child Features of this Epic in Azure DevOps, then share
+  > the Feature or PBI/Bug IDs and I will create test cases for each."
 - Do NOT call `create_and_link_test_cases` with an Epic ID under any circumstances.
 
 **HARD STOP 2 — Always ask for user confirmation before creating test cases for a Feature.**

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

@@ -200,10 +200,18 @@ qa-playwright-generator:generate_playwright_code(
 
 ### Step 6 — Write files
 
+First retrieve the file contents from the playwright generator's cache:
+
+```
+qa-playwright-generator:get_generated_files(cache_key: "<cache_key from Step 5>")
+```
+
+Then write to Helix:
+
 ```
 qa-helix-writer:write_helix_files(
   helix_root = "<helix_root>",
-  files      = <files dict from generate_playwright_code>,
+  files      = <files dict from get_generated_files>,
   mode       = "<recommendation from Step 2>"
 )
 ```
@@ -318,8 +326,9 @@ Before calling `write_helix_files`:
 - [ ] Every `*.steps.ts` in the `files` dict uses Cucumber expression syntax (not regex).
 - [ ] `mode` matches `recommendation` — never override without user instruction.
 - [ ] `force_scaffold` is `false` unless the user explicitly asked to regenerate.
-- [ ] The `files` dict comes directly from `generate_playwright_code` or
-      `scaffold_locator_repository` — never manually constructed.
+- [ ] The `files` dict comes from `get_generated_files(cache_key)` — never manually
+      constructed. `generate_playwright_code` and `scaffold_locator_repository` return
+      a `cache_key`; call `get_generated_files` to retrieve file contents.
 - [ ] After writing, the `deduplication` field has been reviewed and reported.
 
 ---