@qa-gentic/stlc-agents 1.0.25 → 1.0.26

package/src/stlc_agents/webhook_orchestrator/models.py

@@ -0,0 +1,63 @@
+"""
+models.py — Shared data models for the webhook orchestrator.
+"""
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class Platform(str, enum.Enum):
+    ADO  = "ado"
+    JIRA = "jira"
+
+
+class PipelineStage(str, enum.Enum):
+    TEST_CASES         = "test_cases"
+    GHERKIN_PLAYWRIGHT = "gherkin_playwright"
+    FULL               = "full"
+    SKIP               = "skip"
+
+
+@dataclass
+class WebhookEvent:
+    platform: Platform
+    work_item_id: str
+    state: str
+    work_item_type: str
+    title: str = ""
+    previous_state: str = ""
+
+    # ADO-specific
+    organization_url: str = ""
+    project_name: str = ""
+
+    # Jira-specific
+    cloud_id: str = ""
+    project_key: str = ""
+
+    # Common optional
+    helix_project_root: str = ""
+    app_base_url: str = ""
+    app_username: str = ""
+    app_password: str = ""
+
+    # LLM
+    llm_provider: str = "anthropic"
+    llm_model: str = ""
+    llm_api_key: str = ""
+    llm_base_url: str = ""
+
+    # Agent extra kwargs
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PipelineResult:
+    success: bool
+    steps: list[str] = field(default_factory=list)
+    error: str = ""
+
+    def to_dict(self) -> dict:
+        return {"success": self.success, "steps": self.steps, "error": self.error}

package/src/stlc_agents/webhook_orchestrator/orchestrator.py

@@ -0,0 +1,103 @@
+"""
+orchestrator.py — Routes webhook events to the appropriate agent pipeline.
+
+State → Pipeline mapping
+────────────────────────
+Active / In Progress / Approved  → test_cases  (Agent 1 for ADO, Agent 5 for Jira)
+Resolved / Done / Closed         → gherkin_playwright (Agents 2 → 3 → 4)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+from .models import Platform, PipelineResult, PipelineStage, WebhookEvent
+
+# Re-export models so existing importers (webhook_bridge.py) continue to work.
+__all__ = [
+    "Platform", "PipelineResult", "PipelineStage", "WebhookEvent",
+    "classify_state", "run_pipeline",
+]
+
+logger = logging.getLogger("stlc.orchestrator")
+
+_ADO_TEST_CASE_STATES = frozenset({
+    "active", "approved", "committed", "in progress", "in review", "ready for testing",
+})
+_ADO_FULL_PIPELINE_STATES = frozenset({
+    "resolved", "done", "closed", "completed", "released",
+})
+_JIRA_TEST_CASE_STATES = frozenset({
+    "in progress", "active", "in development", "in review",
+    "ready for qa", "approved",
+})
+_JIRA_FULL_PIPELINE_STATES = frozenset({
+    "resolved", "done", "closed", "completed", "released",
+})
+_SKIP_TYPES = frozenset({"epic", "test case", "test suite", "test plan"})
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# State classifier — routing logic only
+# ──────────────────────────────────────────────────────────────────────────────
+
+def classify_state(event: WebhookEvent) -> PipelineStage:
+    wi_type = (event.work_item_type or "").lower()
+    if wi_type in _SKIP_TYPES:
+        return PipelineStage.SKIP
+
+    # Explicit full-pipeline override takes priority over state-based routing.
+    if (
+        event.extra.get("pipeline") == "full"
+        or os.environ.get("STLC_FULL_PIPELINE", "").lower() == "true"
+    ):
+        return PipelineStage.FULL
+
+    state = (event.state or "").lower()
+    if event.platform == Platform.ADO:
+        if state in _ADO_TEST_CASE_STATES:
+            return PipelineStage.TEST_CASES
+        if state in _ADO_FULL_PIPELINE_STATES:
+            return PipelineStage.GHERKIN_PLAYWRIGHT
+    else:
+        if state in _JIRA_TEST_CASE_STATES:
+            return PipelineStage.TEST_CASES
+        if state in _JIRA_FULL_PIPELINE_STATES:
+            return PipelineStage.GHERKIN_PLAYWRIGHT
+
+    return PipelineStage.SKIP
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Entry point — delegates entirely to the appropriate pipeline module
+# ──────────────────────────────────────────────────────────────────────────────
+
+async def run_pipeline(event: WebhookEvent) -> PipelineResult:
+    stage = classify_state(event)
+    logger.info(
+        "Pipeline stage: %s (platform=%s wi=%s state=%s)",
+        stage, event.platform, event.work_item_id, event.state,
+    )
+
+    if stage == PipelineStage.SKIP:
+        return PipelineResult(success=True, steps=["skipped"])
+
+    if stage == PipelineStage.FULL:
+        from .pipelines.full_pipeline import run
+    elif stage == PipelineStage.TEST_CASES:
+        if event.platform == Platform.ADO:
+            from .pipelines.ado_test_cases import run
+        else:
+            from .pipelines.jira_test_cases import run
+    else:
+        from .pipelines.gherkin_playwright import run
+
+    try:
+        return await asyncio.wait_for(run(event), timeout=600)
+    except asyncio.TimeoutError:
+        return PipelineResult(
+            success=False,
+            steps=[f"{stage.value}: wi={event.work_item_id}"],
+            error="Pipeline timed out after 600s",
+        )

package/src/stlc_agents/webhook_orchestrator/pipelines/_base.py

@@ -0,0 +1,57 @@
+"""
+_base.py — Shared utilities for pipeline modules.
+
+Each pipeline module imports mcp_servers() and event_env() from here.
+"""
+from __future__ import annotations
+
+import os
+import pathlib
+import sys
+
+from ..models import WebhookEvent
+
+_IS_WINDOWS = sys.platform == "win32"
+# project_root/.venv/bin  (5 parents up from this file inside src/stlc_agents/webhook_orchestrator/pipelines/)
+_BIN_DIR = (
+    pathlib.Path(__file__).parent.parent.parent.parent.parent.resolve()
+    / ".venv"
+    / ("Scripts" if _IS_WINDOWS else "bin")
+)
+_EXT = ".exe" if _IS_WINDOWS else ""
+
+
+def mcp_servers(*names: str) -> dict:
+    """Build an MCP config dict containing only the named server executables."""
+    return {
+        "mcpServers": {
+            name: {"command": str(_BIN_DIR / f"{name}{_EXT}"), "args": []}
+            for name in names
+        }
+    }
+
+
+def event_env(event: WebhookEvent) -> dict[str, str]:
+    """Merge event-level credentials into a copy of os.environ for subprocess isolation."""
+    env: dict[str, str] = dict(os.environ)
+    if event.organization_url:
+        env["ADO_ORGANIZATION_URL"] = event.organization_url
+    if event.project_name:
+        env["ADO_PROJECT_NAME"] = event.project_name
+    if event.cloud_id:
+        env["JIRA_CLOUD_ID"] = event.cloud_id
+    if event.llm_provider:
+        env["LLM_PROVIDER"] = event.llm_provider
+    if event.llm_model:
+        env["LLM_MODEL"] = event.llm_model
+    if event.llm_api_key:
+        env["LLM_API_KEY"] = event.llm_api_key
+    if event.llm_base_url:
+        env["LLM_BASE_URL"] = event.llm_base_url
+    if event.app_base_url:
+        env["APP_BASE_URL"] = event.app_base_url
+    if event.app_username:
+        env["APP_USERNAME"] = event.app_username
+    if event.app_password:
+        env["APP_PASSWORD"] = event.app_password
+    return env

package/src/stlc_agents/webhook_orchestrator/pipelines/ado_test_cases.py

@@ -0,0 +1,55 @@
+"""
+ado_test_cases.py — Agent 1 pipeline: generate and link test cases for an ADO work item.
+
+Delegates entirely to qa-test-case-manager.
+The agent server owns all test-case generation logic; this module only defines
+the task and the stop conditions the LLM must respect.
+"""
+from __future__ import annotations
+
+import logging
+
+from ..agent_runner import run_agent_loop
+from ..models import PipelineResult, WebhookEvent
+from ._base import event_env, mcp_servers
+
+logger = logging.getLogger("stlc.pipeline.ado_test_cases")
+
+
+def _task_prompt(event: WebhookEvent) -> str:
+    wi_type = (event.work_item_type or "").lower()
+    feature_note = (
+        "This is a Feature work item. The tool will return confirmation_required=true — "
+        "treat it as auto-confirmed and proceed to create_and_link_test_cases.\n"
+        if wi_type == "feature" else ""
+    )
+    return (
+        f"You are a QA automation agent running in webhook mode — auto-confirm all prompts.\n\n"
+        f"Task: Generate and link test cases for ADO work item {event.work_item_id}.\n"
+        f"  Organisation: {event.organization_url}\n"
+        f"  Project:      {event.project_name}\n"
+        f"  Type:         {event.work_item_type}\n"
+        f"  State:        {event.state}\n"
+        f"{feature_note}\n"
+        f"Use the qa-test-case-manager tools to complete this task.\n\n"
+        f"Stop immediately if:\n"
+        f"  - The work item is an Epic (tool returns epic_not_supported)\n"
+        f"  - Linked test cases already exist (get_linked_test_cases returns non-empty list)\n"
+    )
+
+
+async def run(event: WebhookEvent) -> PipelineResult:
+    label = f"ado-test-cases: wi={event.work_item_id}"
+    success, error = await run_agent_loop(
+        mcp_config=mcp_servers("qa-test-case-manager"),
+        prompt=_task_prompt(event),
+        llm_provider=event.llm_provider,
+        llm_model=event.llm_model,
+        llm_api_key=event.llm_api_key,
+        llm_base_url=event.llm_base_url,
+        env=event_env(event),
+        work_item_id=event.work_item_id,
+    )
+    if not success:
+        return PipelineResult(success=False, steps=[label], error=error)
+    return PipelineResult(success=True, steps=[label, "completed"])

package/src/stlc_agents/webhook_orchestrator/pipelines/full_pipeline.py

@@ -0,0 +1,202 @@
+"""
+full_pipeline.py — All 6 STLC steps in a single agent loop.
+
+Runs the complete pipeline end-to-end:
+  1. Fetch work item
+  2. Deduplication pre-flight (get_linked_test_cases + list_helix_tree)
+  3. Create and link test cases
+  4. Generate and attach Gherkin
+  5. Capture live app context (requires APP_BASE_URL)
+  6. Generate Playwright TypeScript
+  6b. Write to Helix project on disk
+
+Agents: qa-test-case-manager, qa-gherkin-generator,
+        qa-playwright-generator, qa-helix-writer.
+
+Triggered by:
+  - event.extra["pipeline"] == "full"
+  - env var STLC_FULL_PIPELINE=true
+"""
+from __future__ import annotations
+
+import logging
+import os
+
+from ..agent_runner import run_agent_loop
+from ..models import Platform, PipelineResult, WebhookEvent
+from ._base import event_env, mcp_servers
+
+logger = logging.getLogger("stlc.pipeline.full")
+
+_AGENTS = (
+    "qa-test-case-manager",
+    "qa-gherkin-generator",
+    "qa-playwright-generator",
+    "qa-helix-writer",
+)
+
+
+def _task_prompt(event: WebhookEvent) -> str:
+    wi_id      = event.work_item_id
+    wi_type    = (event.work_item_type or "").lower()
+    is_feature = wi_type == "feature"
+    is_ado     = event.platform == Platform.ADO
+
+    # ── Platform context ────────────────────────────────────────────────────
+    if is_ado:
+        platform_label = "ADO"
+        platform_ctx   = (
+            f"  Organisation: {event.organization_url}\n"
+            f"  Project:      {event.project_name}\n"
+        )
+        if is_feature:
+            fetch_step   = f"1. fetch_feature_hierarchy(work_item_id={wi_id})"
+            attach_tool  = "attach_gherkin_to_feature"
+        else:
+            fetch_step   = f"1. fetch_work_item_for_gherkin(work_item_id={wi_id})"
+            attach_tool  = "attach_gherkin_to_work_item"
+    else:
+        platform_label = "Jira"
+        platform_ctx   = (
+            f"  Cloud ID:  {event.cloud_id}\n"
+            f"  Project:   {event.project_key}\n"
+        )
+        fetch_step  = f"1. fetch_work_item_for_gherkin(work_item_id={wi_id})"
+        attach_tool = "attach_gherkin_to_work_item"
+
+    # ── App credentials (event fields take priority over env vars) ──────────
+    app_url      = event.app_base_url or os.environ.get("APP_BASE_URL", "")
+    app_username = event.app_username or os.environ.get("APP_USERNAME", "")
+    app_password = event.app_password or os.environ.get("APP_PASSWORD", "")
+
+    # ── Helix root ──────────────────────────────────────────────────────────
+    helix_root = event.helix_project_root
+
+    # ── Deduplication pre-flight ────────────────────────────────────────────
+    if helix_root:
+        dedup_block = (
+            f"DEDUPLICATION PRE-FLIGHT — run these BEFORE any creation steps:\n"
+            f"  a) get_linked_test_cases(work_item_id={wi_id}) — store as existing_test_cases.\n"
+            f"  b) list_helix_tree(helix_root={helix_root!r}) — check for files matching\n"
+            f"     '*{wi_id}*' in both the 'features' AND 'steps' categories.\n"
+            f"  If existing_test_cases is non-empty AND both Helix categories have matching files,\n"
+            f"  this work item is fully covered — STOP and report the existing paths.\n\n"
+        )
+    else:
+        dedup_block = (
+            f"DEDUPLICATION PRE-FLIGHT — run this BEFORE any creation step:\n"
+            f"  a) get_linked_test_cases(work_item_id={wi_id}) — store as existing_test_cases.\n\n"
+        )
+
+    # ── Step 3: test case creation ──────────────────────────────────────────
+    feature_auto_confirm = (
+        "     Auto-confirm if the tool returns confirmation_required=true.\n"
+        if is_feature else ""
+    )
+
+    # ── Steps 5–6: live capture + code generation ───────────────────────────
+    if app_url:
+        capture_step = (
+            f"5. capture_app_context(\n"
+            f"     app_url={app_url!r},\n"
+            f"     app_username={app_username!r},\n"
+            f"     app_password={app_password!r},\n"
+            f"     gherkin_content=<gherkin from step 4>)\n"
+            f"   STOP if result.locator_source='gherkin-inferred' OR result.abort=true OR result.error is set.\n"
+            f"   Only proceed to step 6 when locator_source='playwright-mcp-verified' AND context_map is non-empty.\n"
+        )
+        pw_step = (
+            f"6. generate_playwright_code(\n"
+            f"     gherkin_content=<gherkin from step 4>,\n"
+            f"     context_map=<context_map from step 5>)\n"
+            f"   Store the cache_key from the result.\n"
+        )
+        step_offset = 6
+    else:
+        capture_step = (
+            "5. STOP — APP_BASE_URL is not configured.\n"
+            "   A live context_map is required to generate correct locators.\n"
+            "   Placeholder selectors are not acceptable output.\n"
+            "   To unblock: set APP_BASE_URL (+ APP_USERNAME / APP_PASSWORD) in .env,\n"
+            "   start 'npx @playwright/mcp@latest --port 8931', then re-trigger.\n"
+            "   Do NOT call generate_playwright_code without a verified context_map.\n"
+        )
+        pw_step     = ""
+        step_offset = 4
+
+    # ── Steps 6b: Helix write ───────────────────────────────────────────────
+    if helix_root and app_url:
+        n = step_offset
+        helix_steps = (
+            f"{n+1}. inspect_helix_project(helix_root={helix_root!r})\n"
+            f"   Proceed regardless of framework_state or missing_infra — do NOT stop after inspect.\n"
+            f"{n+2}. write_helix_files(helix_root={helix_root!r}, cache_key=<cache_key from step {n}>)\n"
+            f"   Pass cache_key directly — do NOT pass a files dict.\n"
+            f"   This step is MANDATORY — the pipeline is not complete until write_helix_files succeeds.\n"
+        )
+    elif helix_root:
+        # APP_BASE_URL missing — Playwright steps skipped, but still report Helix state
+        helix_steps = (
+            f"5b. inspect_helix_project(helix_root={helix_root!r})\n"
+            f"    Report current state; no write_helix_files without generated code.\n"
+        )
+    else:
+        helix_steps = ""
+
+    # ── Stop conditions ─────────────────────────────────────────────────────
+    stop_conditions = (
+        "\nStop immediately if:\n"
+        "  - fetch returns epic_not_supported or an error\n"
+        "  - APP_BASE_URL is empty (steps 5+ require a live context_map)\n"
+        "  - capture_app_context returns locator_source='gherkin-inferred', abort=true, or any error field\n"
+        "  - capture_app_context returns an empty context_map\n"
+        "  - generate_and_attach_gherkin returns status='duplicate' or 'already_attached'\n"
+        f"  - Deduplication pre-flight finds existing .feature + .steps.ts for WI #{wi_id}\n"
+        "\nNEVER call generate_playwright_code unless capture_app_context returned\n"
+        "  locator_source='playwright-mcp-verified' with a non-empty context_map.\n"
+        "  Gherkin-inferred locators reference elements that do not exist in the real app.\n"
+    )
+
+    return (
+        f"You are a QA automation agent running in webhook mode — auto-confirm all prompts.\n\n"
+        f"Task: Run the FULL STLC pipeline (test cases + Gherkin + Playwright + Helix) for\n"
+        f"{platform_label} work item {wi_id}.\n"
+        f"  Type:  {event.work_item_type}\n"
+        f"  State: {event.state}\n"
+        f"{platform_ctx}\n"
+        f"{dedup_block}"
+        f"Steps (execute in order):\n"
+        f"{fetch_step}\n"
+        f"   Store result as work_item_summary.\n"
+        f"2. create_and_link_test_cases(work_item_id={wi_id}, ...)\n"
+        f"   Derive test cases from work_item_summary acceptance criteria.\n"
+        f"   SKIP if existing_test_cases from dedup pre-flight is non-empty.\n"
+        f"{feature_auto_confirm}"
+        f"3. {attach_tool}(work_item_id={wi_id}, ...)\n"
+        f"   Generate BDD scenarios from work_item_summary.\n"
+        f"   SKIP if Helix dedup pre-flight found a matching .feature file.\n"
+        f"   Store gherkin_content from result.\n"
+        f"4. validate_gherkin_content(gherkin_content=<from step 3>, scope='work_item')\n"
+        f"   Proceed only if valid=true.\n"
+        f"{capture_step}"
+        f"{pw_step}"
+        f"{helix_steps}"
+        f"{stop_conditions}"
+    )
+
+
+async def run(event: WebhookEvent) -> PipelineResult:
+    label = f"full-pipeline: wi={event.work_item_id}"
+    success, error = await run_agent_loop(
+        mcp_config=mcp_servers(*_AGENTS),
+        prompt=_task_prompt(event),
+        llm_provider=event.llm_provider,
+        llm_model=event.llm_model,
+        llm_api_key=event.llm_api_key,
+        llm_base_url=event.llm_base_url,
+        env=event_env(event),
+        work_item_id=event.work_item_id,
+    )
+    if not success:
+        return PipelineResult(success=False, steps=[label], error=error)
+    return PipelineResult(success=True, steps=[label, "completed"])

package/src/stlc_agents/webhook_orchestrator/pipelines/gherkin_playwright.py

@@ -0,0 +1,156 @@
+"""
+gherkin_playwright.py — Agents 2 → 3 → 4 pipeline.
+
+Generates Gherkin, Playwright tests, and writes output to the Helix repo.
+Delegates to: qa-gherkin-generator, qa-playwright-generator, qa-helix-writer.
+The agent servers own all generation logic; this module only defines the task
+sequence and the stop conditions the LLM must respect.
+"""
+from __future__ import annotations
+
+import logging
+import os
+
+from ..agent_runner import run_agent_loop
+from ..models import Platform, PipelineResult, WebhookEvent
+from ._base import event_env, mcp_servers
+
+logger = logging.getLogger("stlc.pipeline.gherkin_playwright")
+
+_AGENTS = ("qa-gherkin-generator", "qa-playwright-generator", "qa-helix-writer")
+
+
+def _task_prompt(event: WebhookEvent) -> str:
+    wi_type = (event.work_item_type or "").lower()
+    is_feature = wi_type == "feature"
+
+    # ── Step 1: fetch ────────────────────────────────────────────────────────
+    if event.platform == Platform.ADO:
+        if is_feature:
+            fetch_step   = f"1. fetch_feature_hierarchy({event.work_item_id})"
+            attach_tool  = "attach_gherkin_to_feature"
+            platform_ctx = (
+                f"  Organisation: {event.organization_url}\n"
+                f"  Project:      {event.project_name}\n"
+            )
+        else:
+            fetch_step  = f"1. fetch_work_item_for_gherkin({event.work_item_id})"
+            attach_tool = "attach_gherkin_to_work_item"
+            platform_ctx = (
+                f"  Organisation: {event.organization_url}\n"
+                f"  Project:      {event.project_name}\n"
+            )
+    else:
+        fetch_step   = f"1. fetch_work_item_for_gherkin({event.work_item_id})"
+        attach_tool  = "attach_gherkin_to_work_item"
+        platform_ctx = (
+            f"  Cloud ID:    {event.cloud_id}\n"
+            f"  Project:     {event.project_key}\n"
+        )
+
+    # ── Step 2: gherkin ──────────────────────────────────────────────────────
+    gherkin_step = f"2. generate_and_attach_gherkin — generate BDD scenarios and attach via {attach_tool}"
+
+    # ── Step 3: optional live capture ───────────────────────────────────────
+    app_url      = os.environ.get("APP_BASE_URL", "")
+    app_username = os.environ.get("APP_USERNAME", "")
+    app_password = os.environ.get("APP_PASSWORD", "")
+
+    if app_url:
+        capture_step = (
+            f"3. capture_app_context("
+            f"app_url={app_url!r}, "
+            f"app_username={app_username!r}, "
+            f"app_password={app_password!r}, "
+            f"gherkin_content=<gherkin from step 2>)\n"
+            f"   STOP if result contains locator_source='gherkin-inferred' — "
+            f"the Playwright MCP server must be reachable. Do not proceed with inferred selectors.\n"
+        )
+        pw_step     = "4. generate_playwright_code(gherkin_content=<gherkin>, context_map=<from step 3>)"
+        step_offset = 4
+    else:
+        # No APP_BASE_URL — cannot capture live selectors; pipeline must not produce placeholder output.
+        capture_step = (
+            "3. STOP — APP_BASE_URL is not configured.\n"
+            "   Context mapping is required to generate correct locators. Placeholder selectors\n"
+            "   are not acceptable output. To unblock this pipeline:\n"
+            "     a) Set APP_BASE_URL (and optionally APP_USERNAME / APP_PASSWORD) in .env\n"
+            "     b) Start the Playwright MCP server: npx @playwright/mcp@latest --port 8931\n"
+            "     c) Re-trigger the webhook.\n"
+            "   Do NOT call generate_playwright_code without a verified context_map.\n"
+        )
+        pw_step     = ""
+        step_offset = 3
+
+    # ── Helix steps (optional) ───────────────────────────────────────────────
+    helix_root = event.helix_project_root
+    if helix_root:
+        n = step_offset
+        helix_steps = (
+            f"{n+1}. inspect_helix_project(helix_root={helix_root!r})\n"
+            f"   NOTE: inspect result is for context only — proceed to the next steps regardless of\n"
+            f"   framework_state or missing_infra. Do NOT stop after inspect.\n"
+            f"{n+2}. write_helix_files(helix_root={helix_root!r}, cache_key=<cache_key from step {step_offset}>)\n"
+            f"   Pass cache_key directly — do NOT pass a files dict, do NOT call get_generated_files first.\n"
+            f"   This step is MANDATORY — the pipeline is not complete until write_helix_files succeeds.\n"
+        )
+    else:
+        helix_steps = ""
+
+    # ── Deduplication pre-flight (only when helix_root is set) ──────────────
+    wi_id = event.work_item_id
+    if helix_root:
+        dedup_preflight = (
+            f"DEDUPLICATION PRE-FLIGHT — run this BEFORE the steps below:\n"
+            f"  Call list_helix_tree(helix_root={helix_root!r}).\n"
+            f"  If files matching '*{wi_id}*' already exist in BOTH the 'features' AND 'steps'\n"
+            f"  categories, this work item has already been fully processed.\n"
+            f"  STOP immediately and report the existing file paths — do not regenerate.\n\n"
+        )
+        dedup_stop = (
+            f"  - Deduplication pre-flight found existing .feature and .steps.ts files for WI #{wi_id}\n"
+        )
+    else:
+        dedup_preflight = ""
+        dedup_stop = ""
+
+    stop_conditions = (
+        f"\nStop immediately if:\n"
+        f"  - fetch returns epic_not_supported or an error\n"
+        f"  - generate_and_attach_gherkin returns status='duplicate' or 'already_attached'\n"
+        f"{dedup_stop}"
+    )
+
+    return (
+        f"You are a QA automation agent running in webhook mode — auto-confirm all prompts.\n\n"
+        f"Task: Run the full STLC generation pipeline for "
+        f"{'ADO' if event.platform == Platform.ADO else 'Jira'} work item {wi_id}.\n"
+        f"  Type:  {event.work_item_type}\n"
+        f"  State: {event.state}\n"
+        f"{platform_ctx}\n"
+        f"{dedup_preflight}"
+        f"Steps:\n"
+        f"{fetch_step}\n"
+        f"{gherkin_step}\n"
+        f"{capture_step}"
+        f"{pw_step}\n"
+        f"{helix_steps}"
+        f"{stop_conditions}"
+    )
+
+
+async def run(event: WebhookEvent) -> PipelineResult:
+    label = f"gherkin-playwright: wi={event.work_item_id}"
+    success, error = await run_agent_loop(
+        mcp_config=mcp_servers(*_AGENTS),
+        prompt=_task_prompt(event),
+        llm_provider=event.llm_provider,
+        llm_model=event.llm_model,
+        llm_api_key=event.llm_api_key,
+        llm_base_url=event.llm_base_url,
+        env=event_env(event),
+        work_item_id=event.work_item_id,
+    )
+    if not success:
+        return PipelineResult(success=False, steps=[label], error=error)
+    return PipelineResult(success=True, steps=[label, "completed"])