@salesforce/afv-skills 1.24.0 → 1.26.0

package/skills/dx-devops-test-suite-assignments-configure/references/error-handling.md

@@ -0,0 +1,14 @@
+# Error Handling — Suite Assignments (Modes B–D)
+
+Never expose raw API error messages, stack traces, or JSON payloads to the user. Map response status codes to plain-language messages.
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The request was invalid. Check that all suite and stage IDs are correct and the event type is valid." |
+| 403 | "You don't have permission to modify suite assignments on this pipeline." |
+| 404 | "The pipeline or stage was not found." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Mode A (recommendation) errors
+
+Mode A makes only read queries. If a `sf data query` fails, report the problem in plain language and stop — do NOT fabricate suite names, recommendations, or coverage data. If no suites are assigned to the Review trigger, state that explicitly ("No test suites are currently assigned to the Review trigger for this pipeline").

package/skills/dx-devops-test-suite-assignments-configure/references/prerequisite-checks.md

@@ -0,0 +1,112 @@
+# Prerequisite Checks — Shared DevOps Center Gate
+
+Shared environment gate for every DevOps Center testing skill. Run these checks **before** any query or system call. On any failure, surface the plain-language message and stop until the user resolves it — never proceed to a write with an unverified environment.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data (pipelines, stages, test suites, executions) lives in the Salesforce org — NOT in the local repository. Never search the filesystem for pipeline configuration. Always query the org using `sf data query` or `sf api request rest`.
+
+**Object model — use the STANDARD objects, never the `sf_devops__` managed package:** DevOps Center testing data lives in standard platform objects — `DevopsPipeline`, `DevopsPipelineStage`, `DevopsPipelineStageTrigger`, `DevopsTestSuite`, `DevopsTestSuiteStage`, `DevopsTestSuiteExecution`, `DevopsProject`, `WorkItem`. Do **NOT** query the legacy managed-package objects (`sf_devops__Pipeline__c`, `sf_devops__Pipeline_Stage__c`, etc.) and do **NOT** gate on a `PackageLicense` / namespace check for `sf_devops`. "DevOps Center installed" is determined **solely** by whether `DevopsPipeline` is queryable and returns records (Prerequisite 4) — never by the presence of the `sf_devops__` namespace. If a `sf_devops__*` object is missing, that is expected and is NOT evidence that DevOps Center is uninstalled.
+
+## How skills use this
+
+Run Prerequisites 1–4 in order. Prerequisite 5 (stage) is run **only** when the operation targets a specific pipeline stage (configuring a gate, running/retriggering a suite, mapping a suite). Carry forward the resolved `doce-org-alias`, `pipelineId`, and (when applicable) `stageId`.
+
+Resolve the **DevOps Center org alias** without asking the user unless genuinely ambiguous:
+1. If the user named an org alias in their message, use it.
+2. Otherwise, use the default org (`sf org display --json`, no `--target-org`).
+3. Only if the default org has no `DevopsPipeline` records (Prereq 4 fails), ask: "Which org alias is your DevOps Center org?"
+
+---
+
+## Prerequisite 1 — Salesforce org: active login
+
+```bash
+sf org list --json
+```
+
+Look for at least one entry in `result.nonScratchOrgs`, `result.scratchOrgs`, or `result.sandboxes` with `"connectedStatus": "Connected"`.
+
+- **Pass:** at least one org is Connected
+- **Fail:** no orgs listed, or all show a non-connected status
+
+**On fail:** "No authenticated Salesforce org found. Run `sf org login web --alias <your-alias>` in your terminal, then come back."
+
+---
+
+## Prerequisite 2 — Agentforce DX plugin installed
+
+```bash
+sf plugins --json
+```
+
+Look for a plugin entry whose `name` contains `plugin-agent`, `agentforce`, or `einstein` (case-insensitive).
+
+- **Pass:** plugin found
+- **Fail:** no matching entry
+
+**On fail:** "The Agentforce DX Plugin is not installed. Run `sf plugins install @salesforce/plugin-agent`, then restart the IDE and try again."
+
+---
+
+## Prerequisite 3 — DevOps Center org authenticated
+
+```bash
+sf org display --target-org <doce-org-alias> --json
+```
+
+Check that `"connectedStatus"` is `"Connected"`.
+
+- **Pass:** Connected
+- **Fail:** expired session or error
+
+**On fail:** "Your DevOps Center org session has expired. Run `sf org login web --alias <doce-org-alias>` to re-authenticate."
+
+---
+
+## Prerequisite 4 — Pipeline identified
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, CreatedDate FROM DevopsPipeline ORDER BY Name ASC" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+- **Pass (exactly one):** use it automatically — do NOT ask.
+- **Pass (multiple):** if the user already named a pipeline, match by name. Otherwise display a numbered list and ask:
+  ```text
+  Found <N> pipelines:
+  1. <Name>
+  2. <Name>
+  Which pipeline would you like to work with?
+  ```
+- **Fail (no records):** "No DevOps Center pipeline found. Create a project and pipeline in DevOps Center before using the DevOps Testing Skills."
+- **Fail (unsupported object):** "DevOps Center does not appear to be installed on `<doce-org-alias>`. Check that you're pointing at the correct org."
+
+---
+
+## Prerequisite 5 — Pipeline stage identified (conditional)
+
+Run **only** when the operation targets a specific stage (e.g. configuring a quality gate).
+
+If the user's message already names a stage (e.g. "Integration", "Staging", "Production"), use that name directly — do NOT ask again. Look up its Id:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' AND Name = '<stageName>'" \
+  --target-org <doce-org-alias> --json
+```
+
+Only if no stage is mentioned, fetch the full list and ask which one:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' ORDER BY Name ASC" \
+  --target-org <doce-org-alias> --json
+```
+
+Then ask: "Which pipeline stage are we working with?" — do NOT ask for an org alias; stages are resolved by name from the pipeline.
+
+- **Pass:** stage Id and Name confirmed
+- **Deferred:** not required until the operation needs it

package/skills/{recommending-devops-tests/SKILL.md → dx-devops-test-suite-assignments-configure/references/recommendation-logic.md}

@@ -1,28 +1,18 @@
----
-name: recommending-devops-tests
-description: "Analyzes a commit diff and available DevOps Center test suite metadata to recommend the most relevant existing test suites, then flags coverage gaps where no suite covers a new method — via pure reasoning, no system calls beyond the prerequisite queries. Use this skill when a developer wants to know which test suites to run for a specific commit or diff, what tests cover their changes, or wants suite recommendations at commit time. TRIGGER when: the user asks which test suites to run for a commit/diff, asks what tests cover their changes, or asks for suite recommendations before promoting. DO NOT TRIGGER when: authoring new tests (use platform-apex-test-generate) or running sf apex run test directly (use platform-apex-test-run)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
-
-# Recommending DevOps Tests
+# Mode A — Recommend Suites for a Commit/Diff
 
-**Type:** Pure reasoning — no system calls beyond the prerequisite data-fetch queries documented below.
+**Type:** Pure reasoning — no system calls beyond the prerequisite data-fetch queries documented below. No writes.
 
 **What it does:** Analyzes the commit diff and available suite metadata to recommend the most relevant existing test suites assigned to the Review pipeline stage. Flags coverage gaps where no suite covers a new method.
 
----
-
 ## Prerequisites
 
-Load and follow the `checking-devops-prerequisites` skill first (Prerequisites 1–4). This skill needs a confirmed DevOps Center org alias and pipeline Id before it can proceed.
+Run Prerequisites 1–4 (`references/prerequisite-checks.md`). A confirmed DevOps Center org alias and `pipelineId` are required before proceeding. No stage prompt — recommendation reads the pipeline-level Review trigger.
 
 ---
 
 ## Step 1 — Fetch suite metadata
 
-Before reasoning can begin, fetch the test suite metadata assigned to the Review pipeline stage. This requires two queries.
+Two queries are required before reasoning.
 
 **1a — Find the Review pipeline stage trigger:**
 
@@ -48,9 +38,7 @@ Each row provides: `TestSuiteId`, `TestSuite.Name`, `IsQualityGateEnabled`, and
 
 > Note: Do NOT use the beta `/connect/devops/.../testSuites` endpoint — it returns empty results. Query `DevopsTestSuiteStage` directly as shown above.
 
-Never expose raw API errors or raw JSON to the user. If a query fails, report the problem in plain language and stop.
-
-The commit diff comes from the user or surrounding context.
+Never expose raw API errors or raw JSON to the user. If a query fails, report the problem in plain language and stop. The commit diff comes from the user or surrounding context.
 
 ---
 
@@ -58,8 +46,6 @@ The commit diff comes from the user or surrounding context.
 
 ### 1 — Classify the diff by change type
 
-Parse the diff file extensions and paths to determine what types of changes were made:
-
 | File pattern | Change type |
 |---|---|
 | `*.cls`, `*.trigger` | Apex |
@@ -71,7 +57,7 @@ A single commit may contain multiple change types. Identify all of them.
 
 ### 2 — Map change types to test providers
 
-For each change type identified, match against the `testProviderName` of the fetched suites:
+For each change type, match against the `testProviderName` of the fetched suites:
 
 | Change type | Match suites whose `testProviderName` contains |
 |---|---|
@@ -81,7 +67,7 @@ For each change type identified, match against the `testProviderName` of the fet
 | LWC / JavaScript | `LWC` or `JavaScript` |
 | Code Analyzer (any) | `Code Analyzer` — then sub-filter by suite name convention: `recommended` → Apex/general rules (suggest for Apex and Java changes), `html` → suggest for HTML/LWC template changes, `css` → suggest for CSS changes. If no suite name matches the convention, suggest all Code Analyzer suites and note the ambiguity. |
 
-Only recommend suites whose provider matches at least one change type in the diff. Suites from non-matching providers are excluded from the recommendation.
+Only recommend suites whose provider matches at least one change type in the diff. Suites from non-matching providers are excluded.
 
 ### 3 — Rank matched suites
 
@@ -129,9 +115,7 @@ Coverage gaps (new methods — manual authoring required):
 
 Only recommend existing suites. Never suggest generating new tests. If gaps exist, direct the developer to author tests manually and explain exactly which methods need coverage.
 
----
-
-## Related skills
+## How recommendations feed assignment
 
-- To analyze failures from a run, use `analyzing-test-failures`.
-- To actually execute a recommended suite, use `running-devops-test-suite`.
+- A relevant suite that exists but is **not assigned** to the stage → use **Mode B/C** (`references/suite-assignment-modes.md`) to assign it.
+- To actually execute a recommended suite, use **`dx-devops-test-suite-run`**.

package/skills/dx-devops-test-suite-assignments-configure/references/suite-assignment-modes.md

@@ -0,0 +1,99 @@
+# Modes B–D — Assign / Map / Manage Suite Classes
+
+All three modes use the same `testSuiteStages` endpoint (`references/api-endpoint.md`). They differ in scope and the confirmation pattern required.
+
+## Prerequisites & shared inputs
+
+Run Prerequisites 1–4 **and** Prerequisite 5 (stage). You need:
+
+| Variable | Description |
+|---|---|
+| `doce-org-alias` | Prerequisite 1 |
+| `pipelineId` | Prerequisite 4 (pipeline selection) |
+| `stageId` | Prerequisite 5 (stage selection) |
+| `event` | `Pre-Promote`, `Post-Promote`, or `Review` |
+
+---
+
+## Mode B — Assign a single suite to a stage
+
+Use when a relevant test suite already exists but is not yet linked to a stage and the user wants to add it as a single one-off assignment.
+
+**Additional inputs:**
+
+| Variable | Description |
+|---|---|
+| `testSuiteId` | ID of the suite to assign |
+| `testSuiteName` | Name of the suite (for display in confirmation) |
+
+**Confirmation gate (required before any API call):**
+
+> "The suite `<testSuiteName>` is not currently assigned to the `<stageName>` stage (`<event>`). Would you like me to assign it now?"
+
+Do not proceed until the user confirms.
+
+**On success:**
+
+> "Suite `<testSuiteName>` has been assigned to the `<stageName>` stage (`<event>`)."
+
+---
+
+## Mode C — Map multiple suites to a stage
+
+Use when configuring suite-to-stage mappings across a pipeline or assigning multiple suites as part of a testing strategy.
+
+**Additional inputs:**
+
+| Input | Description |
+|---|---|
+| `testSuiteOperations` | List of `{testSuiteId, action: "add"\|"remove"}` |
+
+**MANDATORY IMPACT PREVIEW — required before any changes.** Do not call the API until the user has confirmed the preview:
+
+> "Here's the suite mapping I'll apply:
+>
+> | Suite | Stage | Event | Action |
+> |---|---|---|---|
+> | `<suiteName>` | `<stageName>` | `<event>` | Add |
+> | `<suiteName2>` | `<stageName>` | `<event>` | Remove |
+>
+> Confirm to apply all changes?"
+
+Only proceed after the user explicitly confirms.
+
+**On success:**
+
+> "Suite mapping applied. `<N>` suite(s) updated for the `<stageName>` stage."
+
+---
+
+## Mode D — Add/remove test classes in a suite
+
+Use when the user wants to add or remove individual test classes within an existing suite assignment, sync reviewed tests into a suite, or promote tests to a suite.
+
+**Additional inputs:**
+
+| Input | Source |
+|---|---|
+| `testSuiteOperations` | List of `{testSuiteId, action: "add"\|"remove"}` |
+
+**Governance rules:**
+
+- **Never call this without explicit approval.** AI-reviewed or modified tests must be re-presented to the user before this call is made.
+- Rejected tests must be EXCLUDED from the payload — do not include them even if they were previously in the suite.
+- If tests were modified during review, re-present the final list before requesting confirmation.
+
+**Confirmation gate (required — do not skip):**
+
+> "I'm about to sync the following changes to the test suite:
+> - **Add:** `<testSuiteName1>`, `<testSuiteName2>`
+> - **Remove:** `<testSuiteName3>`
+> - Stage: `<stageName>` | Event: `<event>`
+>
+> Confirm?"
+
+Only proceed after explicit confirmation.
+
+**On success:**
+
+> "Test suite updated successfully for the `<stageName>` stage."

package/skills/dx-devops-test-suite-run/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: dx-devops-test-suite-run
+description: "Runs DevOps Center test suites on a pipeline stage (Pre-Promote, Post-Promote, or Review event) end to end: triggers async execution via the Connect API after an explicit confirmation gate, then polls by runId at provider-specific intervals until it completes, fails, or times out, and hands results to failure analysis. Also retriggers a quality gate after fixes, but only once coverage meets the threshold. Use this skill when a user wants to run, kick off, or launch test suites on a stage, re-run a quality gate, or watch an in-progress run to completion. TRIGGER when: the user wants to run/launch suites on a stage, execute tests before or after promotion, re-run a quality gate after fixing failures, unblock a blocked promotion after adding tests, or poll/watch an in-progress run. DO NOT TRIGGER when: running sf apex run test directly (use running-apex-tests), or configuring a NEW gate or threshold (use dx-devops-test-pipeline-configure)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Run a DevOps Center Test Suite
+
+Triggers a DevOps Center test suite execution and watches it to completion. Running and polling are two halves of one operation — never poll without first having (or being handed) a `runId`.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data lives in the Salesforce org — NOT the local repo. Always query the org with `sf data query` or `sf api request rest`.
+
+---
+
+## Prerequisites
+
+Run the prerequisite checks in `references/prerequisite-checks.md` — Prerequisites 1–4 **and** Prerequisite 5 (stage), since this skill operates on a specific stage. You need the confirmed `doce-org-alias`, `pipelineId`, and `stageId`.
+
+## Inputs required
+
+| Input | How to obtain |
+|---|---|
+| `pipelineId` | Prerequisite 4 (pipeline selection) |
+| `stageId` | Prerequisite 5 (pipeline stage confirmation) |
+| `event` | Confirm with user: `Pre-Promote`, `Post-Promote`, or `Review` |
+| `testSuiteIds` | Confirmed suite IDs from selection or recommendation |
+| `doce-org-alias` | Prerequisite 1 |
+
+---
+
+## Step 1 — Trigger execution
+
+### Confirmation gate
+
+**This call mutates org state — do not proceed without explicit user confirmation.** Before calling the API, show:
+
+> "I'm about to run tests with the following configuration:
+> - Pipeline: `<pipelineName>`
+> - Stage: `<stageName>`
+> - Event: `<event>`
+> - Suite(s): `<suiteName(s)>`
+> - Org: `<doce-org-alias>`
+>
+> Shall I proceed?"
+
+Do not make the API call until the user confirms.
+
+### API call
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/stage/execute" \
+  --method POST \
+  --body '{
+    "stageId": "<stageId>",
+    "event": "<event>",
+    "testSuiteIds": ["<suiteId1>", "<suiteId2>"]
+  }' \
+  --target-org <doce-org-alias>
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `stageId` | string | The ID of the pipeline stage to execute tests on |
+| `event` | string | `Pre-Promote`, `Post-Promote`, or `Review` |
+| `testSuiteIds` | string[] | One or more test suite IDs to execute |
+
+### On success
+
+Extract the `runId` (execution ID) from the response. Inform the user:
+
+> "Tests are running in `<doce-org-alias>`. I'll update you when results are ready."
+
+Then proceed **immediately** to Step 2 (polling) with the `runId`.
+
+### On error
+
+See `references/error-handling.md`. If the org rejects execution (e.g. `environmentId: null`, or `classIdList is null or empty — no tests to execute`), read the actual error, explain the root cause and required fix in plain language, and finish cleanly. **Do not retry in a loop and do not fabricate a `runId` or results.**
+
+---
+
+## Step 2 — Poll until completion
+
+**Confirmation required:** No — polling is automatic and read-only.
+
+Poll the execution record by `runId` at the provider-appropriate interval. Full intervals, timeout behavior, and the poll query are in `references/polling-configuration.md`.
+
+Summary of the loop (the `runId` is a `DevopsTestSuiteExecution` Id — poll that object, not `DevopsTestExecution`):
+- Query `DevopsTestSuiteExecution` by `runId` each interval for `Status, Coverage, SuccessCount, FailureCount, QualityGateStatus`.
+- `InProgress` → wait and poll again.
+- `Passed` / `Failed` → surface `Coverage`, `SuccessCount`, `FailureCount`, and `QualityGateStatus` inline (no raw JSON). If `FailureCount > 0`, fetch the child `DevopsTestExecution` failure rows and hand off to **`dx-devops-test-failures-analyze`**.
+- `Error` → the run itself errored (not test failures); surface `ResultDetails`/`Message` in plain language and offer retry or skip.
+- **Timeout** → surface the `runId`, do NOT auto-retry, wait for user instruction.
+
+---
+
+## Retrigger mode (re-running a quality gate)
+
+Use when a promotion was blocked by a gate failure and the coverage gap has since been addressed. **All preconditions, gate, and the retrigger API call are in `references/retrigger-mode.md`.** Key rule: do **not** retrigger unless the latest `Coverage` meets or exceeds the `DevopsQualityGateRule` threshold. After the retrigger returns a new `runId`, hand it to Step 2 (polling).
+
+---
+
+## Related skills
+
+- **`dx-devops-test-failures-analyze`** — receives the failure payload on completion; can also create a fix work item.
+- **`dx-devops-test-suite-assignments-configure`** — recommend which suites to run, or assign a suite to the stage if it isn't linked yet.
+- **`dx-devops-test-pipeline-configure`** — configure a new quality gate or threshold (this skill only re-runs existing gates).

package/skills/dx-devops-test-suite-run/references/error-handling.md

@@ -0,0 +1,31 @@
+# Error Handling — Execution & Polling
+
+Never expose raw API errors, stack traces, or JSON payloads to the user.
+
+## Step 1 — Execute call
+
+| Status | Message to user |
+|---|---|
+| 400 | "The test execution request was invalid. Check that the stage and suite IDs are correct." |
+| 403 | "You don't have permission to run tests on this pipeline. Check your DevOps Testing API access." |
+| 404 | "The pipeline or stage was not found. It may have been deleted." |
+| 500 | "The DevOps Center org returned a server error. Try again in a few minutes." |
+
+## Org-side execution rejections (read the real error, explain, finish — do NOT loop)
+
+| Org error | Explanation to user |
+|---|---|
+| `environmentId: null` | "The environment connection isn't resolving for this stage. Re-authenticate or reconnect the stage's environment in DevOps Center, then try again." |
+| `classIdList is null or empty — no tests to execute` | "The assigned suite(s) contain no test classes, so there's nothing to run. Add test classes to the suite (via dx-devops-test-suite-assignments-configure) and try again." |
+
+In both cases: attempt the call once, explain the root cause and required fix, finish cleanly. Do NOT retry in a loop and do NOT fabricate a `runId` or results.
+
+**Empty-org / no-data case:** If the stage has no assigned suites, report that clearly and do NOT call the execute endpoint or fabricate a suite/run.
+
+## Step 2 — Polling
+
+If no `DevopsTestExecution` record matches the runId, report it gracefully and do not fabricate result data. On timeout, surface the runId and wait for user instruction — never auto-retry.
+
+## Do NOT use `sf apex run test`
+
+That command is for the `running-apex-tests` skill, not DevOps Center test suites.

package/skills/dx-devops-test-suite-run/references/polling-configuration.md

@@ -0,0 +1,78 @@
+# Polling Configuration (Step 2)
+
+**Confirmation required:** No — polling is automatic and read-only. No user confirmation gate is needed.
+
+**What it does:** Polls the DevOps Center org for the status of an async test execution until it completes, times out, or fails.
+
+## Prerequisites
+
+You need an active `runId` (from Step 1, the execute call) and the confirmed `doce-org-alias`. If org context is not yet established, run Prerequisites 1–3 (`references/prerequisite-checks.md`).
+
+## Inputs
+
+| Input | Source |
+|---|---|
+| `runId` | Returned by the Step 1 execute call (or supplied by the user for an in-progress run) |
+| `testType` | Derived from the suite's test provider (Apex, Code Analyzer, UI/Provar, Flow) |
+| `doce-org-alias` | Established via prerequisites |
+
+If the user is watching an already-running execution, resolve the `runId` by querying the most recent `DevopsTestExecution` for the relevant trigger, or use the runId the user provides.
+
+## Polling intervals
+
+| Test type | Poll interval | Max wait | Timeout action |
+|---|---|---|---|
+| Apex unit tests | 15 seconds | 5 minutes | Surface runId, offer retry |
+| Code Analyzer | 10 seconds | 3 minutes | Surface runId, offer retry |
+| UI tests (Provar) | 60 seconds | 20 minutes | Surface runId, mark as pending |
+| Flow tests | 20 seconds | 8 minutes | Surface runId, offer retry |
+
+## Object model — read the right object
+
+The `runId` returned by the execute call is a **`DevopsTestSuiteExecution`** record Id (the suite-level run). Poll *that* object — it holds the status and the aggregate results. Per-test detail lives on child `DevopsTestExecution` records linked by `DevopsTestSuiteExecutionId`.
+
+| Object | Role | Key fields |
+|---|---|---|
+| `DevopsTestSuiteExecution` (poll this) | Suite-level run = the `runId` | `Status`, `Coverage`, `SuccessCount`, `FailureCount`, `SuccessRate`, `FailureRate`, `QualityGateStatus`, `ExecutionEndTime`, `ResultDetails`, `ReportUrl` |
+| `DevopsTestExecution` (per-test detail) | One row per test, linked via `DevopsTestSuiteExecutionId` | `Status`, `Message`, `Severity`, `ResultDetails`, `DevopsTestId` |
+
+> Do NOT query `TestsRan`, `TestsPassed`, `TestsFailed`, or `CoveragePercentage` — those fields do not exist on either object and the query will fail with `INVALID_FIELD`. Use the field names in the table above.
+
+## Poll query
+
+Query the suite execution record by `runId` on each interval:
+
+```bash
+sf data query \
+  --query "SELECT Id, Status, Coverage, SuccessCount, FailureCount, QualityGateStatus FROM DevopsTestSuiteExecution WHERE Id = '<runId>' LIMIT 1" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Check the `Status` picklist on each poll (valid values: `Passed`, `Failed`, `InProgress`, `Error`):
+- `InProgress` → wait and poll again
+- `Passed` → run completed successfully; surface results
+- `Failed` → run completed with test failures; surface results, then fetch per-test detail (below) and hand off to analysis
+- `Error` → the run itself errored (not a test failure); surface the `ResultDetails`/`Message` in plain language and offer retry or skip
+
+## On timeout
+
+Surface the `runId` to the user:
+> "The test run is taking longer than expected. Your run ID is `<runId>`. You can check the status manually in DevOps Center, or I can keep waiting — what would you prefer?"
+
+Do not automatically retry after timeout. Wait for user instruction.
+
+## On completion
+
+When `Status` is `Passed` or `Failed`, surface `Coverage`, `SuccessCount`, `FailureCount`, and `QualityGateStatus` from the `DevopsTestSuiteExecution` record inline (no raw JSON).
+
+If `FailureCount > 0` (or `Status = Failed`), fetch the per-test failure detail from the child `DevopsTestExecution` records, then pass that payload to the **`dx-devops-test-failures-analyze`** skill:
+
+```bash
+sf data query \
+  --query "SELECT Id, Status, Message, Severity, ResultDetails, DevopsTestId FROM DevopsTestExecution WHERE DevopsTestSuiteExecutionId = '<runId>' AND Status = 'Failed'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+**Empty / no-data case:** If no `DevopsTestSuiteExecution` record matches the runId, report that clearly and do NOT fabricate a runId, status, or result values.

package/skills/dx-devops-test-suite-run/references/prerequisite-checks.md

@@ -0,0 +1,112 @@
+# Prerequisite Checks — Shared DevOps Center Gate
+
+Shared environment gate for every DevOps Center testing skill. Run these checks **before** any query or system call. On any failure, surface the plain-language message and stop until the user resolves it — never proceed to a write with an unverified environment.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data (pipelines, stages, test suites, executions) lives in the Salesforce org — NOT in the local repository. Never search the filesystem for pipeline configuration. Always query the org using `sf data query` or `sf api request rest`.
+
+**Object model — use the STANDARD objects, never the `sf_devops__` managed package:** DevOps Center testing data lives in standard platform objects — `DevopsPipeline`, `DevopsPipelineStage`, `DevopsPipelineStageTrigger`, `DevopsTestSuite`, `DevopsTestSuiteStage`, `DevopsTestSuiteExecution`, `DevopsProject`, `WorkItem`. Do **NOT** query the legacy managed-package objects (`sf_devops__Pipeline__c`, `sf_devops__Pipeline_Stage__c`, etc.) and do **NOT** gate on a `PackageLicense` / namespace check for `sf_devops`. "DevOps Center installed" is determined **solely** by whether `DevopsPipeline` is queryable and returns records (Prerequisite 4) — never by the presence of the `sf_devops__` namespace. If a `sf_devops__*` object is missing, that is expected and is NOT evidence that DevOps Center is uninstalled.
+
+## How skills use this
+
+Run Prerequisites 1–4 in order. Prerequisite 5 (stage) is run **only** when the operation targets a specific pipeline stage (configuring a gate, running/retriggering a suite, mapping a suite). Carry forward the resolved `doce-org-alias`, `pipelineId`, and (when applicable) `stageId`.
+
+Resolve the **DevOps Center org alias** without asking the user unless genuinely ambiguous:
+1. If the user named an org alias in their message, use it.
+2. Otherwise, use the default org (`sf org display --json`, no `--target-org`).
+3. Only if the default org has no `DevopsPipeline` records (Prereq 4 fails), ask: "Which org alias is your DevOps Center org?"
+
+---
+
+## Prerequisite 1 — Salesforce org: active login
+
+```bash
+sf org list --json
+```
+
+Look for at least one entry in `result.nonScratchOrgs`, `result.scratchOrgs`, or `result.sandboxes` with `"connectedStatus": "Connected"`.
+
+- **Pass:** at least one org is Connected
+- **Fail:** no orgs listed, or all show a non-connected status
+
+**On fail:** "No authenticated Salesforce org found. Run `sf org login web --alias <your-alias>` in your terminal, then come back."
+
+---
+
+## Prerequisite 2 — Agentforce DX plugin installed
+
+```bash
+sf plugins --json
+```
+
+Look for a plugin entry whose `name` contains `plugin-agent`, `agentforce`, or `einstein` (case-insensitive).
+
+- **Pass:** plugin found
+- **Fail:** no matching entry
+
+**On fail:** "The Agentforce DX Plugin is not installed. Run `sf plugins install @salesforce/plugin-agent`, then restart the IDE and try again."
+
+---
+
+## Prerequisite 3 — DevOps Center org authenticated
+
+```bash
+sf org display --target-org <doce-org-alias> --json
+```
+
+Check that `"connectedStatus"` is `"Connected"`.
+
+- **Pass:** Connected
+- **Fail:** expired session or error
+
+**On fail:** "Your DevOps Center org session has expired. Run `sf org login web --alias <doce-org-alias>` to re-authenticate."
+
+---
+
+## Prerequisite 4 — Pipeline identified
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, CreatedDate FROM DevopsPipeline ORDER BY Name ASC" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+- **Pass (exactly one):** use it automatically — do NOT ask.
+- **Pass (multiple):** if the user already named a pipeline, match by name. Otherwise display a numbered list and ask:
+  ```text
+  Found <N> pipelines:
+  1. <Name>
+  2. <Name>
+  Which pipeline would you like to work with?
+  ```
+- **Fail (no records):** "No DevOps Center pipeline found. Create a project and pipeline in DevOps Center before using the DevOps Testing Skills."
+- **Fail (unsupported object):** "DevOps Center does not appear to be installed on `<doce-org-alias>`. Check that you're pointing at the correct org."
+
+---
+
+## Prerequisite 5 — Pipeline stage identified (conditional)
+
+Run **only** when the operation targets a specific stage (e.g. configuring a quality gate).
+
+If the user's message already names a stage (e.g. "Integration", "Staging", "Production"), use that name directly — do NOT ask again. Look up its Id:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' AND Name = '<stageName>'" \
+  --target-org <doce-org-alias> --json
+```
+
+Only if no stage is mentioned, fetch the full list and ask which one:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' ORDER BY Name ASC" \
+  --target-org <doce-org-alias> --json
+```
+
+Then ask: "Which pipeline stage are we working with?" — do NOT ask for an org alias; stages are resolved by name from the pipeline.
+
+- **Pass:** stage Id and Name confirmed
+- **Deferred:** not required until the operation needs it