@qa-gentic/agents 1.1.2

package/skills/qa-stlc/generate-playwright-code.md

@@ -0,0 +1,439 @@
+---
+name: generate-playwright-code
+description: >
+  Use this skill whenever the user asks to generate, create, or update Playwright TypeScript
+  automation code for a Feature, PBI, or Bug. Triggers when the user mentions "Playwright",
+  "page object", "locators", "step definitions", "automation", "self-healing", "locator
+  repository", "TimingHealer", "VisualIntentChecker", or asks to automate a Gherkin feature
+  file. Always reads existing attached Playwright files from the ADO work item before generating
+  anything, to avoid duplicate locators, page methods, and step definitions. Works with any ADO
+  work item type: PBI, Bug, or Feature ID.
+compatibility:
+  tools:
+    - qa-playwright-generator:generate_playwright_code
+    - qa-playwright-generator:attach_code_to_work_item
+    - qa-playwright-generator:validate_gherkin_steps
+    - qa-test-case-manager:get_linked_test_cases
+    - qa-gherkin-generator:fetch_feature_hierarchy
+    - playwright:browser_navigate
+    - playwright:browser_snapshot
+    - playwright:browser_fill_form
+    - playwright:browser_click
+    - playwright:browser_file_upload
+---
+
+# Generate Playwright Code Skill
+
+> **Read `AGENT-BEHAVIOR.md` before this skill.** The behavior rules there override any
+> inference. This skill provides the step-by-step workflow only.
+
+Generate production-quality, three-layer self-healing Playwright TypeScript automation from a
+validated Gherkin feature file, using live Playwright MCP snapshots for verified locators.
+Works with any ADO work item type: PBI, Bug, or Feature ID.
+
+---
+
+## Three Healing Layers
+
+Every generated page object implements three layers of self-healing:
+
+| 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 are persisted in `LocatorRepository` — zero overhead on repeat runs.
+HealingDashboard runs at `http://localhost:7890` during test execution for approve/reject.
+
+---
+
+## ⛔ Mandatory Pre-Flight: Deduplication Protocol
+
+Before generating or attaching any file, run the deduplication protocol:
+`skills/deduplication-protocol.md`
+
+The protocol is **work-item-scoped**: PHASE 1 runs once per `work_item_id` and results are
+cached. If `generate-gherkin` already ran for this `work_item_id`, skip PHASE 1 and read from
+`CACHE[work_item_id]` directly. A different `work_item_id` always triggers a fresh PHASE 1.
+
+---
+
+## Step-by-Step Workflow
+
+### Step 1 — Load existing Playwright artifacts from cache
+
+Read from `CACHE[work_item_id]` (populated by the deduplication protocol pre-flight):
+
+```
+CACHE[work_item_id].existing_attachments.locators_ts   → existing locator keys
+CACHE[work_item_id].existing_attachments.page_objects  → existing method names
+CACHE[work_item_id].existing_attachments.steps_files   → existing step strings
+```
+
+If a file exists but content could not be read, treat it as fully covering its domain and
+produce no new file of that type unless you can prove a gap.
+
+---
+
+### Step 2 — GAP CHECK: identify screens you cannot reach and ASK before proceeding
+
+Before navigating the live app, scan the Gherkin feature file for every `Given` step that
+requires a specific app state — a state only reachable by performing a real action (uploading
+a file, submitting a form, triggering an error, completing a multi-step flow).
+
+For each such step, ask: **can I reach this screen right now with the information I have?**
+
+#### Blockers that require a user question before proceeding
+
+| Blocker | Example | What to ask |
+|---|---|---|
+| File upload required to reach a screen | "Given I am on the failure summary screen" — only after uploading a CSV with bad rows | "Please provide the CSV file or tell me which emails to use as known duplicates" |
+| Specific record / ID required | "Given work item #12345 has linked test cases" | "Which org / record should I test against?" |
+| Error state requires specific bad data | "Given the upload is rejected for unsupported format" | "Should I use .txt or .pdf to test the rejection?" |
+| Multi-step prerequisite from a sibling PBI | "Given the mass add has completed" | "Should I replay the upload step, or is there a seed/shortcut?" |
+| Screen only exists after a backend event | "Given the processing is complete" | "Is there a test endpoint I can hit to seed this state?" |
+
+**If any blocker is found, output a question block and wait for answers.**
+
+#### Question format
+
+```
+Before I navigate the live app to capture locators for "<feature title>", I need:
+
+**[Blocker type]: [screen or element name]**
+[One sentence describing what the Gherkin step requires]
+→ [Specific question — what file, what email, what record, what sequence?]
+
+I will not proceed until these are answered, to avoid inventing selectors
+(stability: 0) for screens I cannot reach.
+```
+
+**Only proceed to Step 3 once every blocker is resolved, OR the user explicitly grants
+sign-off to proceed with known `stability: 0` limitations documented.**
+
+---
+
+### Step 3 — Live locator verification through the FULL flow
+
+Navigate through **every screen in the Gherkin feature** — including state-dependent screens —
+using the real test data provided in Step 2. Never snapshot only the landing page and infer.
+
+```
+playwright:browser_navigate(APP_BASE_URL)
+playwright:browser_snapshot()                    ← login screen
+
+playwright:browser_fill_form(fields: [
+  { name: "Email",    type: "textbox", ref: "<ref>", value: "<email>" },
+  { name: "Password", type: "textbox", ref: "<ref>", value: "<password>" }
+])
+playwright:browser_click(ref: "<login-button-ref>")
+playwright:browser_snapshot()                    ← dashboard — verify logged in
+
+← Navigate through EVERY prerequisite step to reach state-dependent screens
+playwright:browser_click(...)                    ← e.g. "Add Users" button
+playwright:browser_click(...)                    ← e.g. "Add Multiple" tab
+playwright:browser_snapshot()                    ← capture screen locators
+
+← Upload real test file (from user's Step 2 answer)
+playwright:browser_file_upload(
+  files: ["<real file path>"],
+  element: "file upload input",
+  ref: "<ref from snapshot>"
+)
+playwright:browser_snapshot()                    ← verify file attached, Next enabled
+
+playwright:browser_click(...)                    ← "Next" / Submit
+playwright:browser_snapshot()                    ← capture processing screen (if any)
+playwright:browser_snapshot()                    ← capture state-dependent result screen
+                                                    ← capture ALL interactive elements here
+
+playwright:browser_click(...)                    ← any further actions (Export, Accept, etc.)
+playwright:browser_snapshot()                    ← capture post-action state
+```
+
+**Rule:** Every locator in the generated `locators.ts` must appear in one of these snapshots.
+If a screen cannot be reached because test data is missing, go back to Step 2 and ask — do
+not assign `stability: 0` and continue silently.
+
+---
+
+### Step 4 — Build the context_map
+
+From each snapshot, map AX tree nodes to locator entries using this stability rank:
+
+| Selector source | Stability |
+|---|---|
+| `data-testid` attribute | 100 |
+| `aria-role` + accessible name | 90 |
+| `id` attribute | 80 |
+| `aria-label` | 70 |
+| `placeholder` text | 60 |
+| Gherkin-inferred (no live verification) | 0 — `⚠ NOT VERIFIED` comment required |
+
+Only include keys NOT already present in the existing `locators.ts` (from Step 1).
+
+**Example context_map (built from Playwright MCP AX snapshots):**
+```json
+{
+  "emailInput":         { "selector": "[data-testid='auth0_login-input-email']",        "intent": "Auth0 login email field",              "stability": 100 },
+  "loginButton":        { "selector": "[data-testid='auth0_login-button-login']",       "intent": "Submit login credentials",             "stability": 100 },
+  "addUsersButton":     { "selector": "[data-testid='person_header-button-add_users']", "intent": "Add Users button, opens slide-out",    "stability": 100 },
+  "addMultipleTab":     { "selector": "[data-testid='person_slider-tab-add_multiple']", "intent": "Add Multiple tab in Add Users panel",  "stability": 100 },
+  "fileInput":          { "selector": "input[type='file']",                             "intent": "Hidden file input for CSV upload",     "stability": 70  },
+  "nextButton":         { "selector": "button:has-text('Next')",                        "intent": "Proceed after file upload",            "stability": 90  },
+  "exportListButton":   { "selector": "button:has-text('Export List')",                 "intent": "Export failed users CSV",              "stability": 90, "visualIntent": true },
+  "failureSummaryTable":{ "selector": "table",                                          "intent": "Failed user rows table",               "stability": 80, "visualIntent": true }
+}
+```
+
+---
+
+### Step 5 — Generate the code
+
+```
+qa-playwright-generator:generate_playwright_code(
+  gherkin_content          : <validated .feature file content>,
+  page_class_name          : "<ScreenName>Page",
+  app_name                 : "<AppName>",
+  context_map              : <context_map from Step 4>,
+  healing_strategy         : "role-label-text-ai",
+  enable_timing_healing    : true,
+  enable_visual_regression : true
+)
+```
+
+The tool produces four files:
+- `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
+- `cucumber-profile.js` snippet — profile config to add to `config/cucumber.js`
+
+---
+
+### Step 6 — Apply the deduplication delta filter
+
+Diff generated output against `CACHE[work_item_id].existing_attachments`:
+
+**locators.ts:** Remove keys already in existing file. Empty delta → skip. Non-empty → attach as `locators.delta.ts`:
+```typescript
+// DELTA — merge these keys into the existing locators.ts
+// Generated: <date> | Work item: #<id>
+```
+
+**{ScreenName}Page.ts:** Remove methods already in existing page object. Empty delta → skip. Non-empty → attach as `{ScreenName}Page.delta.ts` with merge header.
+
+**{feature}.steps.ts:** Remove any `Given(` / `When(` / `Then(` whose step string already exists. Empty delta → skip. Non-empty → attach only net-new steps.
+**CRITICAL: Never re-register an existing step string** — causes `Ambiguous step definition` at runtime.
+
+---
+
+### Step 7 — Delivery gate (mandatory before attaching to ADO)
+
+Before calling `attach_code_to_work_item`, present the following to the user and wait:
+
+```
+I've generated the following Playwright TypeScript files for work item #{id}:
+
+  📄 locators.delta.ts      — {N} new locator keys
+  📄 {ScreenName}Page.delta.ts — {N} new page methods
+  📄 {feature}.steps.delta.ts  — {N} new step definitions
+
+**Do you want me to attach these to ADO work item #{id}? (yes / no)**
+
+Note:
+- Saying yes here only attaches the Playwright files.
+- It does NOT create manual test cases or attach Gherkin files.
+- If you also want those, say so separately.
+```
+
+**Do not call `attach_code_to_work_item` until the user replies "yes".**
+
+If user says "yes", call with 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: "..." }
+  ]
+)
+```
+
+If user says "no": present the files inline. Offer local download only if user says
+"save" or "download". Do not create a local file automatically.
+
+**After attach — STOP. Do not trigger Helix write or any other action automatically.**
+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"
+```
+
+---
+
+## Quality Gates — Do Not Attach Without These
+
+- [ ] Deduplication protocol run — existing locator keys, methods, step strings extracted
+- [ ] **Gap check (Step 2) completed** — every state-dependent screen identified
+- [ ] **All blockers answered by user before any navigation began**
+- [ ] **Live snapshots taken of every screen in the full flow** using real test data
+- [ ] **Zero `stability: 0` locators** for screens reachable with provided test data
+- [ ] Every `stability: 0` locator has `⚠ NOT VERIFIED` comment with explicit user sign-off
+- [ ] No step string re-registers an already-registered Given/When/Then
+- [ ] Page object methods use `LocatorHealer` — never raw `page.click` / `page.fill`
+- [ ] Credentials sourced from `process.env`, not hardcoded
+- [ ] Delta files have merge-instruction comment at top
+
+---
+
+## Locator Stability Reference
+
+| Pattern | Stability | When to use |
+|---|---|---|
+| `[data-testid='...']` | 100 | Always prefer — survives refactors |
+| `role=button[name='...']` | 90 | When data-testid absent |
+| `#id` | 80 | When id is stable and meaningful |
+| `[aria-label='...']` | 70 | Accessibility attributes |
+| `[placeholder='...']` | 60 | Input fields only |
+| Text / position selectors | 0 | Last resort — flag for upgrade |
+
+---
+
+## Explicit Delivery Rules — No Inference
+
+| Decision | Rule |
+|---|---|
+| Generate Playwright code | Always: show file summary and delta counts first |
+| Attach to ADO | Requires explicit "yes" at Step 7 gate |
+| User says "no" at Step 7 | Present files inline; offer local download only if user asks |
+| Local file creation | Only if user says "save" or "download" |
+| Helix-QA disk write | Must be a separate user request — not triggered by ADO attachment |
+| Test case creation | Must be a separate user request — not triggered by this skill |
+| Gherkin attachment | Must be a separate user request — not triggered by this skill |
+| Prior Gherkin "yes" | Has NO bearing on Playwright attachment decision |
+| Prior test case "no" | Has NO bearing on Playwright attachment decision |
+
+**Each artifact delivery is independent. A yes/no for one does not answer any other.**

package/skills/qa-stlc/generate-test-cases.md

@@ -0,0 +1,176 @@
+# Skill: Generate Test Cases from Azure DevOps Work Item
+
+> **Read `AGENT-BEHAVIOR.md` before this skill.** The behavior rules there override any
+> inference. This skill provides the step-by-step workflow only.
+
+Use this skill when asked to generate, create, or write test cases for an Azure DevOps
+PBI, Bug, User Story, or Feature.
+
+---
+
+## 🚨 HARD STOP RULES — Read Before Anything Else
+
+**HARD STOP 0 — Never infer delivery destination.**
+Generating test cases ≠ creating them in ADO. Show the user what you plan to create.
+Get explicit confirmation. Do not auto-submit.
+
+**HARD STOP 1 — Never create test cases for an Epic.**
+Test cases in ADO are always scoped to PBIs, Bugs, or Features — never to Epics.
+If the user provides an Epic ID and asks for test cases:
+- Call `fetch_work_item` with the Epic ID — the tool will return `"error": "epic_not_supported"`.
+- 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?"
+- 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.**
+When the target work item is a Feature, the server will return `"confirmation_required": true`.
+At that point, **stop and ask the user**:
+> "I'm about to create {N} manual test case(s) linked to Feature #{id} — "{title}".
+> Please confirm (yes / no) before I proceed."
+Do not call `create_and_link_test_cases` again until the user replies affirmatively.
+If the user replies 'no' or 'cancel', abort and inform them no test cases were created.
+
+## ⛔ Mandatory Pre-Flight: Deduplication Protocol
+
+Before executing any step below, run the deduplication protocol:
+`skills/deduplication-protocol.md`
+
+The protocol is **work-item-scoped**: PHASE 1 runs once per `work_item_id` and its results
+are cached. If this skill is invoked for the same `work_item_id` that another agent already
+processed, skip PHASE 1 and read from `CACHE[work_item_id]` directly.
+A different `work_item_id` always triggers a fresh PHASE 1.
+
+---
+
+## Steps
+
+### Step 1 — Fetch the work item and existing test cases
+
+**1A — Fetch the work item:**
+Call `fetch_work_item` with the work item ID, organization URL, and project name.
+
+The response contains:
+- `work_item` — title, acceptance_criteria, description, repro_steps (for Bugs), story_points, priority, area_path, iteration_path
+- `parent_feature` — parent Feature if present
+- `existing_test_cases_count` — count of already-linked test cases (use as a signal only)
+- `coverage_hints` — keys derived from AC text flagging areas that need coverage
+
+**1B — Fetch existing test case titles (always, before generating):**
+`existing_test_cases_count` is a count, not the actual titles. Two concurrent runs against the
+same work item will duplicate test cases unless you fetch the real titles first.
+
+```
+qa-test-case-manager:get_linked_test_cases(
+  organization_url : ...
+  project_name     : ...
+  work_item_id     : <same ID>
+)
+```
+
+The response contains a `linked_test_cases` list with `id`, `title`, `state`, `priority`.
+**Skip any test case whose title (or a near-identical paraphrase) already exists in this list.**
+If `existing_test_cases_count` is 0 you may skip the call.
+
+### Step 2 — Determine complexity
+Use `story_points` and the count of distinct acceptance criteria:
+- **Simple** (3–6 TCs): ≤ 2 points or ≤ 2 AC items
+- **Medium** (6–12 TCs): 3–5 points or 3–5 AC items
+- **Complex** (12–18 TCs): > 5 points or > 5 AC items
+
+Add +1 TC for each `coverage_hint` not already addressed.
+
+### Step 3 — Apply the granularity rule
+Ask: "Does this step naturally flow into the next as part of one user journey?" If yes,
+merge into ONE test case with multiple steps. Avoid micro-interaction test cases.
+
+- ✗ BAD: TC="Slide-out opens", TC="File picker appears"
+- ✓ GOOD: TC="User opens profile and initiates photo update" (multi-step)
+
+### Step 4 — Design test cases covering all applicable categories
+
+| Category | Description |
+|---|---|
+| Happy paths | Successful end-to-end flows |
+| Success feedback | Toast/confirmation messages after success |
+| Post-action state | UI reflects the change (photo displayed, count updated) |
+| Validation errors | Invalid input, wrong format, missing required fields |
+| Boundary conditions | Test AT the exact limit stated in ACs (exactly 5 MB, not 4 MB or 6 MB) |
+| Edge cases | Empty state, default state, fallback display (initials avatar) |
+| Negative scenarios | Failure states, error toasts, state unchanged after failure |
+| Data persistence | Data survives page refresh or re-login |
+| Computed/derived state | Values derived from other fields update correctly |
+| Platform-specific | Mobile/webview scenarios when mentioned in ACs |
+| Cancel flows | Cancel/discard discards changes without saving |
+
+Apply every hint in `coverage_hints`. Skip titles already in the `linked_test_cases` list from Step 1B.
+
+### Step 4B — Delivery gate (mandatory — do not skip)
+
+Before calling `create_and_link_test_cases`, present the following to the user and wait:
+
+```
+I've designed {N} test cases for work item #{id} — "{title}".
+
+Here is the list:
+  1. {TC title}
+  2. {TC title}
+  ...
+
+**Do you want me to create these in ADO now? (yes / no)**
+
+Note:
+- Saying yes here only creates test cases — it does not generate Gherkin or Playwright code.
+- If you also want Gherkin or Playwright code, say so separately.
+```
+
+**Do not call `create_and_link_test_cases` until the user replies "yes".**
+**Do not carry this confirmation forward to any other artifact.**
+
+### Step 5 — Create and link
+Call `create_and_link_test_cases` with your test cases. Do NOT specify `area_path` —
+it is automatically inherited from the parent work item.
+
+Each test case:
+- `title` — clear, specific, describes what is being tested
+- `steps` — array of `{ action, expected_result }` — at least 2 steps per TC
+- `priority` — 1=Critical, 2=High (default), 3=Medium, 4=Low
+
+## Example tool call
+
+```json
+{
+  "work_item_id": 12345,
+  "organization_url": "https://dev.azure.com/myorg",
+  "project_name": "MyProject",
+  "test_cases": [
+    {
+      "title": "TC_12345_01 — User uploads valid profile photo and sees success confirmation",
+      "priority": 2,
+      "steps": [
+        {"action": "Navigate to My Profile slide-out", "expected_result": "Profile section opens showing current photo or initials"},
+        {"action": "Click Update Photo and select a valid JPG file under 5 MB", "expected_result": "Image preview is shown in the crop editor"},
+        {"action": "Adjust crop area and click Save", "expected_result": "Success toast 'Profile photo updated' is displayed and photo appears in the header"}
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Explicit Delivery Rules — No Inference
+
+| Decision | Rule |
+|---|---|
+| Generate test cases | Always: show the proposed list first |
+| Create in ADO | Requires explicit "yes" at Step 4B gate |
+| User says "no" at gate | Abort; report "No test cases created" |
+| User confirms Feature test cases | Separate confirmation at HARD STOP 2 — not carried from Step 4B |
+| Generate Gherkin next | Must be a separate user request — not triggered by this skill |
+| Generate Playwright next | Must be a separate user request — not triggered by this skill |
+| Save locally | Only if user explicitly says "save" or "download" |
+
+**Each artifact delivery is independent. A yes/no for one does not answer any other.**