@salesforce/afv-skills 1.18.0 → 1.20.0

package/skills/managing-suite-assignments/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: managing-suite-assignments
+description: "Manages all forms of test suite assignment for DevOps Center pipeline stages via the Connect API testSuiteStages endpoint. Covers three modes: (A) attaching a single suite to a stage as a one-off add, (B) bulk-mapping multiple suites to a stage as a testing strategy with a mandatory impact-preview table before any changes, and (C) adding or removing individual test classes within a suite assignment with governance rules that exclude rejected tests and re-present the final list before committing. TRIGGER when: a suite is found unlinked from a pipeline stage and the user wants to assign it; the user wants to configure suite-to-stage mappings across a pipeline or assign multiple suites to stages as part of a testing strategy; the user wants to add or remove tests in a suite, sync reviewed tests into a suite, or promote tests to a suite. DO NOT TRIGGER when: authoring new test classes (use generating-apex-test) or running tests directly (use running-apex-tests)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Managing Suite Assignments
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4 AND Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, and `stageId` before proceeding in any mode.
+
+| Variable | Description |
+|---|---|
+| `doce-org-alias` | Established in Prerequisite 1 |
+| `pipelineId` | Identified in Prerequisite 4 (pipeline selection) |
+| `stageId` | Identified in Prerequisite 5 (stage selection) |
+| `event` | `Pre-Promote`, `Post-Promote`, or `Review` |
+
+---
+
+## Mode A — Assign a single suite to a stage
+
+Use this mode when a relevant test suite already exists but is not yet linked to a pipeline stage and the user wants to add it as a single one-off assignment.
+
+**Additional inputs required:**
+
+| Variable | Description |
+|---|---|
+| `testSuiteId` | ID of the suite to assign |
+| `testSuiteName` | Name of the suite (for display in confirmation) |
+
+**Confirmation gate**
+
+**Confirmation required before any API call is made.**
+
+Present the following prompt to the user and wait for an affirmative response:
+
+> "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**
+
+Report to the user:
+
+> "Suite `<testSuiteName>` has been assigned to the `<stageName>` stage (`<event>`)."
+
+---
+
+## Mode B — Map multiple suites to a stage
+
+Use this mode when configuring suite-to-stage mappings across a pipeline or assigning multiple suites to stages as part of a testing strategy.
+
+**Additional inputs required:**
+
+| 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 below.**
+
+Present the full mapping summary and wait for explicit confirmation:
+
+> "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 C — Add/remove test classes in a suite
+
+Use this mode 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 required:**
+
+| 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 of tests before requesting confirmation.
+
+**Confirmation gate**
+
+**REQUIRED — do not skip.** Show the user the full list of changes before calling:
+
+> "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 receiving explicit confirmation.
+
+**On success**
+
+Confirm to the user:
+> "Test suite updated successfully for the `<stageName>` stage."
+
+---
+
+## The system call
+
+All three modes use the same endpoint. Substitute all `<placeholder>` values before executing.
+
+```bash
+sf api request rest "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testSuiteStages" --method POST --body '{"pipelineStageId":"<stageId>","event":"<event>","assignments":[{"testSuiteId":"<id>","action":"add|remove"}]}' --target-org <doce-org-alias>
+```
+
+Full payload schema:
+
+```json
+{
+  "pipelineStageId": "<stageId>",
+  "event": "<event>",
+  "assignments": [
+    {"testSuiteId": "<suiteId1>", "action": "add"},
+    {"testSuiteId": "<suiteId2>", "action": "remove"}
+  ]
+}
+```
+
+**Error handling**
+
+Never expose raw API error messages to the user. Map response status codes to the following user-facing 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." |
+
+---
+
+## Related skills
+
+- **`syncing-test-providers`** — use when the suite you want to assign doesn't appear yet; re-syncing the provider pulls in newly added suites.
+- **`recommending-devops-tests`** — use when a suite has not yet been identified and you need a recommendation for which suite to assign.
+- **`configuring-quality-gate`** — use to configure a quality gate on the stage after mapping suites.
+- **`analyzing-test-failures`** — use for failure analysis and suggested improvements to the tests within a suite.

package/skills/platform-agentexchange-partner-offers-enable/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: platform-agentexchange-partner-offers-enable
+description: "Enable or disable the org preference that controls whether a Salesforce org can receive partner offers from the Transactable Marketplace. Use this skill when the user wants to turn partner offer reception on or off for an org. TRIGGER when: user asks to enable or disable partner offers, configure TransactableMarketplaceReceivePartnerOffers, configure enableTransactableMarketplaceReceivePartnerOffers, set up marketplace partner offer reception, toggle the TM partner offers setting, edit a TransactableMarketplacePrivateOffer.settings file, or configure org preferences related to transactable marketplace. DO NOT TRIGGER when: user needs to create or manage the partner offer records themselves, configure marketplace listing settings, or work with SfdcPartnerOffer objects (use deploying-metadata or generating-apex instead)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Enabling Transactable Marketplace Receive Partner Offers Org Preference
+
+This skill configures the `enableTransactableMarketplaceReceivePartnerOffers` org preference via the `TransactableMarketplacePrivateOfferSettings` Metadata API type, which controls whether a Salesforce org is eligible to receive partner offers through the Transactable Marketplace. It is required for subscriber orgs that participate in the TM partner offer flow.
+
+## Scope
+
+- **In scope**: Reading the current value of the pref, enabling or disabling it via Metadata API (`TransactableMarketplacePrivateOfferSettings`), and verifying the change took effect.
+- **Out of scope**: Creating or managing partner offer records, configuring marketplace listings, or any Apex/trigger changes related to offer processing.
+
+---
+
+## Required Inputs
+
+- **Target org alias or username**: The org where the pref should be set. Ask if not provided.
+- **Desired state**: `true` (enable) or `false` (disable). Default: `true`.
+
+---
+
+## Workflow
+
+### Phase 1 — Check current state
+
+1. **Query the current preference value** by running:
+   ```bash
+   sf data query -q "SELECT Preference, Value FROM OrgPreference WHERE Preference = 'TransactableMarketplaceReceivePartnerOffers'" --target-org <alias> --use-tooling-api
+   ```
+   If the record exists and `Value = true`, the pref is already enabled — confirm with the user before proceeding.
+   If the query returns no rows, the pref is not yet set (defaults to `false`).
+
+2. **Resolve the org's package directory** to determine where to write metadata. Run this and use its output as `<packageDir>`:
+   ```bash
+   jq -r '.packageDirectories[0].path // "force-app/main/default"' sfdx-project.json
+   ```
+
+### Phase 2 — Apply the preference
+
+3. **Write the TransactableMarketplacePrivateOfferSettings metadata file** — load `assets/org-pref-template.md` for the exact XML structure, then write the file at:
+   ```text
+   <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
+   ```
+   Set `<enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>` (or `false` if disabling).
+
+4. **Deploy the metadata** to the target org. Before running the deploy, confirm with the user:
+   - [ ] Confirmed the target org alias with the user (deploying to the wrong org is not easily reversible)
+   - [ ] Confirmed the desired state (`true`/`false`) matches the user's intent
+   ```bash
+   sf project deploy start --metadata TransactableMarketplacePrivateOfferSettings --target-org <alias>
+   ```
+
+### Phase 3 — Verify
+
+5. **Confirm the change** by re-running the Tooling API query from step 1 and verifying the `Value` column matches the desired state.
+
+6. **Report to the user** — see Output Expectations below.
+
+---
+
+## Rules / Constraints
+
+| Rule | Rationale |
+|------|-----------|
+| Always query the current value before writing metadata | Avoids unnecessary deploys and detects conflicting changes |
+| Use `TransactableMarketplacePrivateOfferSettings` as the metadata type | This is the concrete type registered in the platform for this pref, not the generic `OrgPreferenceSettings` |
+| The settings file must be named `TransactableMarketplacePrivateOffer.settings` | Metadata API requires the filename to match the settings node name |
+| Do not hardcode `force-app/main/default/` | Always read `sfdx-project.json` for the actual package directory |
+| Never deploy without confirming the org alias with the user | Deploying to the wrong org is not easily reversible |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Tooling API query returns no rows | Pref is unset (defaults to `false`). Safe to create a new settings file. |
+| Deploy fails with `INVALID_TYPE` | The metadata type name is `TransactableMarketplacePrivateOfferSettings` — check the `--metadata` flag value. |
+| Deploy succeeds but value doesn't change | Another settings file in the project may be overriding this one. Search for other `TransactableMarketplacePrivateOffer.settings` files in the project. |
+| `INSUFFICIENT_ACCESS_OR_READONLY` on deploy | User running the deploy must have the "Modify All Data" or org preference admin permission in the target org. |
+| Pref not visible in UI | `enableTransactableMarketplaceReceivePartnerOffers` is not surfaced in Setup UI — the Tooling API query is the only way to verify it. |
+| Available from API version 67.0+ only | The type is available from API v67.0 — deploying against an older API version will fail. |
+
+---
+
+## Output Expectations
+
+After completing all phases, report:
+
+```text
+Org: <alias>
+Preference: enableTransactableMarketplaceReceivePartnerOffers
+Previous value: <true|false|unset>
+New value: <true|false>
+File written: <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
+Deploy status: Success
+```
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `assets/org-pref-template.md` | Phase 2, step 3 — use as the exact XML structure for the settings file |
+| `examples/org-preference-settings.xml` | To verify the generated file matches expected format |

package/skills/platform-agentexchange-partner-offers-enable/assets/org-pref-template.md

@@ -0,0 +1,27 @@
+# TransactableMarketplacePrivateOfferSettings XML Template
+
+Use this exact structure when writing the settings metadata file.
+
+## File path
+
+```text
+<packageDir>/settings/TransactableMarketplacePrivateOffer.settings
+```
+
+## Template
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<TransactableMarketplacePrivateOfferSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>
+</TransactableMarketplacePrivateOfferSettings>
+```
+
+Replace `true` with `false` to disable.
+
+## Notes
+
+- The metadata type is `TransactableMarketplacePrivateOfferSettings`, available from API version 67.0+.
+- This type is registered with `apiCreateAllowed="false"` and `apiDeleteAllowed="false"` — it can only be updated, not created or deleted via the API. This does NOT mean you should skip writing the file: the preference always exists in the org with a default value, so writing a new local settings file and deploying it is treated as an update by the Metadata API and is always valid.
+- The `xmlns` attribute is required; omitting it causes a deploy parse error.
+- The field name is `enableTransactableMarketplaceReceivePartnerOffers` (note the `enable` prefix).

package/skills/platform-agentexchange-partner-offers-enable/examples/org-preference-settings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<TransactableMarketplacePrivateOfferSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>
+</TransactableMarketplacePrivateOfferSettings>

package/skills/polling-test-results/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: polling-test-results
+description: "Polls a DevOps Center async test execution by runId until it completes, fails, or times out — using read-only SOQL on the execution record at provider-specific intervals (Apex 15s/5m, Code Analyzer 10s/3m, Provar UI 60s/20m, Flow 20s/8m) — then surfaces results. Use this skill when a test suite run is in progress and the user is waiting on results, or immediately after running a suite. TRIGGER when: a test suite run is in progress and the user is waiting on results, or immediately after running a suite and a runId is available. DO NOT TRIGGER when: there is no active runId."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# polling-test-results
+
+**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` (returned by the `running-devops-test-suite` skill) and the confirmed `doce-org-alias`. If org context is not yet established, load `checking-devops-prerequisites` first (Prerequisites 1–3).
+
+---
+
+## Inputs required
+
+| Input | Source |
+|---|---|
+| `runId` | Returned by the `running-devops-test-suite` skill |
+| `testType` | Derived from the suite's test provider (Apex, Code Analyzer, UI/Provar, Flow) |
+| `doce-org-alias` | Established via `checking-devops-prerequisites` |
+
+## Polling configuration
+
+| 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 |
+
+## Poll query
+
+Query the execution record by `runId` on each interval:
+
+```bash
+sf data query \
+  --query "SELECT Id, Status, TestsRan, TestsPassed, TestsFailed, CoveragePercentage FROM DevopsTestExecution WHERE Id = '<runId>' LIMIT 1" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Check the `Status` field on each poll:
+- `Queued` / `Running` → wait and poll again
+- `Completed` → proceed to result analysis
+- `Failed` → surface error 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
+
+Pass the full result payload to the `analyzing-test-failures` skill for reasoning. Surface `Coverage`, `SuccessCount`, `FailureCount`, and `QualityGateStatus` inline. Do not surface raw JSON to the user.
+
+---
+
+## Related skills
+
+- Runs are started by `running-devops-test-suite` (including its retrigger mode)
+- Failure analysis is handled by `analyzing-test-failures`

package/skills/recommending-devops-tests/SKILL.md

@@ -0,0 +1,137 @@
+---
+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 generating-apex-test) or running sf apex run test directly (use running-apex-tests)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Recommending DevOps Tests
+
+**Type:** Pure reasoning — no system calls beyond the prerequisite data-fetch queries documented below.
+
+**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.
+
+---
+
+## Step 1 — Fetch suite metadata
+
+Before reasoning can begin, fetch the test suite metadata assigned to the Review pipeline stage. This requires two queries.
+
+**1a — Find the Review pipeline stage trigger:**
+
+```bash
+sf data query \
+  --query "SELECT Id FROM DevopsPipelineStageTrigger WHERE TriggerType = 'Review' AND RelatedRecordId = '<pipelineId>'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Record the `Id` returned as `<reviewTriggerId>`.
+
+**1b — Fetch suites assigned to that trigger:**
+
+```bash
+sf data query \
+  --query "SELECT Id, TestSuiteId, TestSuite.Name, IsQualityGateEnabled, DevopsQualityGateId FROM DevopsTestSuiteStage WHERE DevopsPipelineStageTriggerId = '<reviewTriggerId>'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+Each row provides: `TestSuiteId`, `TestSuite.Name`, `IsQualityGateEnabled`, and `DevopsQualityGateId` (when a gate is configured).
+
+> 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.
+
+---
+
+## Reasoning steps
+
+### 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 |
+| `*.flow-meta.xml`, `*.flow` | Flow |
+| `*.java` | Java |
+| `*.js`, `*.html` (LWC paths) | LWC / JavaScript |
+
+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:
+
+| Change type | Match suites whose `testProviderName` contains |
+|---|---|
+| Apex | `Apex` |
+| Flow | `Flow` |
+| Java | `Java` |
+| 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.
+
+### 3 — Rank matched suites
+
+Within each matched provider group, rank suites by:
+1. `triggerType` alignment — `Pre-Promote` suites first for commit-time checks
+2. Quality gate presence — suites with a `qualityGateRuleName` are higher priority (they gate promotion)
+3. Suite name relevance — if the suite name contains a term from the modified file names, boost it
+
+### 4 — Flag new methods with no suite coverage
+
+For any new method added in the diff, flag it as a gap regardless of provider matching:
+> "⚠ `processRefund()` in `OrderService.cls` is a new method. No existing suite can confirm it's covered until tests are authored and linked."
+
+### 5 — Return the recommendation list
+
+Group recommendations by change type so it's clear why each suite was suggested.
+
+---
+
+## Output format
+
+```text
+Recommended suite(s) for this commit:
+
+Apex changes detected (OrderService.cls, InvoiceService.cls):
+1. <SuiteName> — Apex Test Provider | Trigger: Pre-Promote | Gate: <gateName or none>
+2. <SuiteName2> — Apex Test Provider | Trigger: Post-Promote | Gate: <gateName or none>
+
+Flow changes detected (OrderApproval.flow):
+1. <SuiteName3> — Flow Test Provider | Trigger: Pre-Promote | Gate: <gateName or none>
+
+Code Analyzer — Apex rules:
+1. <SuiteName4> — Code Analyzer | Trigger: Pre-Promote | Gate: <gateName or none>
+
+No matching suite found for:
+- LWC changes — no LWC test suite is assigned to this stage
+
+Coverage gaps (new methods — manual authoring required):
+- `processRefund()` in `OrderService.cls` — new method, not yet covered by any suite
+```
+
+---
+
+## v1 constraint
+
+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
+
+- To analyze failures from a run, use `analyzing-test-failures`.
+- To actually execute a recommended suite, use `running-devops-test-suite`.

package/skills/running-devops-test-suite/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: running-devops-test-suite
+description: "Triggers async execution of one or more DevOps Center test suites on a pipeline stage (Pre-Promote, Post-Promote, or Review event) via the Connect API, after an explicit user confirmation gate, then hands off to result polling via the `polling-test-results` skill. Also re-runs (retriggers) a quality gate after fixes — but only once validation confirms the coverage threshold is now met. TRIGGER when: the user wants to run, kick off, or launch test suites on a pipeline stage; execute tests before or after a promotion; trigger a Pre-Promote, Post-Promote, or Review-event run; re-run a quality gate after fixing failures; retry a failed gate once coverage is met; or unblock a blocked promotion after adding tests. DO NOT TRIGGER when: running sf apex run test directly (use running-apex-tests); or configuring a NEW gate or threshold (use configuring-quality-gate)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Running a DevOps Center Test Suite
+
+## Prerequisites
+
+Load and follow `checking-devops-prerequisites` first — run Prerequisites 1–4 AND Prerequisite 5 (pipeline stage), since this skill operates on a specific stage. You need the confirmed `doce-org-alias`, `pipelineId`, and `stageId` before proceeding.
+
+## Inputs required before calling this skill
+
+| Input | How to obtain |
+|---|---|
+| `pipelineId` | From Prerequisite 4 (pipeline selection) |
+| `stageId` | From Prerequisite 5 (pipeline stage confirmation) |
+| `event` | Confirm with user: `Pre-Promote` or `Post-Promote` (or `Review` if the context is a review environment) |
+| `testSuiteIds` | Confirmed suite IDs from the suite selection or recommendation step |
+| `doce-org-alias` | Established in Prerequisite 1 |
+
+## Confirmation gate
+
+**This call mutates org state — do not proceed without explicit user confirmation.**
+
+Before calling the API, show the user:
+
+> "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>
+```
+
+### Body schema
+
+| 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` (or execution ID) from the response. Inform the user:
+
+> "Tests are running in `<doce-org-alias>`. I'll update you when results are ready."
+
+Immediately hand off the `runId` to the `polling-test-results` skill to begin the polling loop.
+
+## On error
+
+| 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." |
+
+Never expose raw API errors to the user.
+
+---
+
+## Retrigger mode (re-running a quality gate)
+
+Use this mode when a promotion was blocked by a quality gate failure and the coverage gap has since been addressed.
+
+### Extra preconditions — all must be true before proceeding
+
+1. The `Coverage` field on the latest `DevopsTestSuiteExecution` meets or exceeds the threshold defined in the `DevopsQualityGateRule`
+2. The user has explicitly asked to retrigger the gate
+3. The same `pipelineId`, `stageId`, and `event` from the blocked promotion are known
+
+If coverage is still below threshold, do **not** retrigger. Instead, respond:
+
+> "Coverage is still at `<X>%`, below the `<threshold>%` gate. The gate cannot be retriggered until the threshold is met. Here are the remaining uncovered methods: `<list>`."
+
+Do not retry. Explain what must be resolved first and stop.
+
+### Inputs required for retrigger
+
+| Input | Source |
+|---|---|
+| `pipelineId` | From the blocked promotion context |
+| `stageId` | From the blocked promotion context |
+| `event` | Same event type that originally blocked (`Pre-Promote` or `Post-Promote`) |
+| `suiteIds` | Same suites that were originally run |
+| `doce-org-alias` | Established in Prerequisite 1 |
+
+### Confirmation gate (retrigger)
+
+Before executing the API call, present this confirmation prompt and wait for explicit user approval:
+
+> "Coverage is confirmed at `<X>%`, which meets the `<threshold>%` gate. I'll retrigger the quality gate check for the `<stageName>` stage (`<event>`). Confirm?"
+
+Only proceed after the user confirms. If the user declines, stop without making any API call.
+
+### API call (retrigger)
+
+Uses the same Connect API stage/execute endpoint:
+
+```bash
+sf api request rest "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/stage/execute" --method POST --body '{"stageId":"<stageId>","event":"<event>","testSuiteIds":["<suiteId1>"]}' --target-org <doce-org-alias>
+```
+
+After the call returns a `runId`, hand off to the `polling-test-results` skill with the new `runId` to monitor the execution result.
+
+### Error handling (retrigger)
+
+If the API returns an error indicating the gate cannot be retriggered, respond with:
+
+> "The quality gate cannot be retriggered right now. Reason: `<plain-language summary>`. Here's what needs to be resolved first: `<list>`."
+
+Never expose raw API error details to the user.
+
+---
+
+## Related skills
+
+- **`polling-test-results`** — poll for async run results after receiving the `runId`
+- **`recommending-devops-tests`** — recommend which suites to run first before triggering execution
+- **`managing-suite-assignments`** — assign or map a suite to a pipeline stage if it isn't linked yet
+- **`configuring-quality-gate`** — configure a new gate or threshold