@salesforce/afv-skills 1.24.0 → 1.26.0

package/skills/dx-devops-test-pipeline-configure/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: dx-devops-test-pipeline-configure
+description: "Configures DevOps Center pipeline testing infrastructure: enables a test provider so its suites become available, re-syncs a configured provider to pull in new suites, or creates a quality gate with rules on a stage. Routes by intent across three modes after running shared prerequisite checks and an explicit confirmation gate. Use this skill when a user wants to set up, configure, enable, sync, or refresh a test provider, or set/configure a quality gate or coverage threshold on a DevOps Center pipeline stage. TRIGGER when: the user wants to configure/enable/add/set up a test provider, re-sync or refresh a provider's suite list, pull in new suites, or set/configure a quality gate, coverage threshold, or testing benchmark on a stage. DO NOT TRIGGER when: assigning existing suites to a stage (use dx-devops-test-suite-assignments-configure), running or retriggering a suite (use dx-devops-test-suite-run), or non-DevOps-Center work."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Configure DevOps Center Pipeline Testing Infrastructure
+
+Sets up and configures a DevOps Center pipeline's testing infrastructure. This skill handles three closely related "configure your pipeline" operations that share the same org context, prerequisites, and entity scope (the pipeline level). Pick the mode that matches the user's intent.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data (pipelines, stages, providers, suites, gates) lives in the Salesforce org — NOT the local repo. Never search the filesystem for pipeline configuration. Always query the org with `sf data query` or `sf api request rest`.
+
+---
+
+## Step 1 — Run prerequisites first (always)
+
+Before any query or system call, run the prerequisite checks in `references/prerequisite-checks.md`. On any failure, surface the plain-language message and stop — never write to an unverified environment.
+
+- **Modes A & B (provider configure/sync):** run Prerequisites 1–4 (org login, Agentforce DX plugin, DevOps Center org auth, pipeline identified). Prerequisite 5 (stage) is **not** required — providers are configured at the pipeline level.
+- **Mode C (quality gate):** run Prerequisites 1–4 **and** Prerequisite 5 (stage). Prereq 5 gives the `DevopsPipelineStage` only — the target `DevopsTestSuiteStage` record Id is resolved separately in Mode C's Step 0 (trigger → suite-stage row).
+
+Carry forward the resolved `doce-org-alias`, `pipelineId`, and (Mode C) `stageId` / `testSuiteStageId`.
+
+---
+
+## Step 2 — Select the mode
+
+| If the user wants to… | Mode | Follow |
+|---|---|---|
+| Enable / set up / add a provider that is **not yet configured** | **A — Configure a test provider** | `references/configuring-test-provider.md` |
+| Re-sync / refresh an **already-configured** provider to pull in new suites | **B — Sync a configured provider** | `references/syncing-test-providers.md` |
+| Set / configure a quality gate, coverage threshold, or testing benchmark on a stage | **C — Configure a quality gate** | `references/configuring-quality-gate.md` |
+
+**Disambiguating A vs B (the critical decision):** First fetch the pipeline's providers (`GET .../testProviders?status=all`) — both modes start there. Then:
+
+- Provider is **Available** (not configured) → **Mode A** (configure).
+- Provider is **Configured** but suites are stale/missing → **Mode B** (sync).
+- Provider is **Configured** and the user can't see suites *when assigning to a stage* → this is a **stage-assignment gap, not a configuration gap**. Redirect to `dx-devops-test-suite-assignments-configure`.
+
+⚠ **Never POST to the configure endpoint for an already-configured provider** — it creates duplicate `DevopsPipelineTestProvider` records. See `references/gotchas.md`.
+
+---
+
+## Step 3 — Confirmation gate (required in every mode)
+
+Every mode mutates org state and **must** show a confirmation gate before any write. Each mode's reference file contains its exact gate wording (Mode C additionally requires a mandatory impact preview before the gate). Do not call any write API until the user gives an affirmative response. If the user declines, stop without writing.
+
+---
+
+## Step 4 — Execute and report
+
+Follow the chosen reference file for the exact API calls, success messages, and error handling:
+
+- `references/configuring-test-provider.md` — Mode A
+- `references/syncing-test-providers.md` — Mode B
+- `references/configuring-quality-gate.md` — Mode C
+- `references/error-handling.md` — consolidated status-code → plain-language tables for all modes
+- `references/gotchas.md` — duplicate-provider trap, API-name differences, trigger-type rules
+
+Never expose raw API errors, stack traces, or JSON payloads to the user — always translate to plain language.
+
+---
+
+## Related skills
+
+- **`dx-devops-test-suite-assignments-configure`** — after configuring/syncing a provider, assign or map its suites to a stage; also recommends which suites to run for a commit.
+- **`dx-devops-test-suite-run`** — run a suite, or retrigger a quality gate after fixes meet the threshold.
+- **`dx-devops-test-failures-analyze`** — explain failures from a run and optionally create a fix work item.

package/skills/dx-devops-test-pipeline-configure/references/configuring-quality-gate.md

@@ -0,0 +1,133 @@
+# Mode C — Configure a Quality Gate
+
+Creates a DevOps Center quality gate with associated rules (`PASS_PERCENTAGE`, `SEVERITY`, `ESSENTIAL`) and links it to a pipeline-stage suite assignment, after a mandatory impact preview and explicit confirmation.
+
+## Prerequisites
+
+Run Prerequisites 1–4 **and** Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, and `stageId`. Prereq 5 resolves only the **`DevopsPipelineStage`** — it does **not** give you the `DevopsTestSuiteStage` record. Resolve that separately in Step 0 below.
+
+## Inputs required
+
+| Input | Source |
+|---|---|
+| `name` | User-provided name for the quality gate |
+| `rules` | List of `{type, threshold?}` — see rule types below |
+| `doce-org-alias` | Prerequisite 1 |
+| `event` | `Pre-Promote`, `Post-Promote`, or `Review` — which trigger the gate applies to |
+| `testSuiteName` | The suite the gate will gate (the gate links to a specific suite-on-stage) |
+| `testSuiteStageId` | Target `DevopsTestSuiteStage` record Id — **resolved in Step 0**, not from Prereq 5 |
+
+---
+
+## Step 0 — Resolve the target `DevopsTestSuiteStage` record
+
+A quality gate links to a specific suite assigned to a stage's trigger, represented by a `DevopsTestSuiteStage` record. That object is keyed by `DevopsPipelineStageTriggerId` + `TestSuiteId` (it is **not** linked directly to `DevopsPipelineStage`), so resolve it in two queries.
+
+**0a — Find the stage's trigger for the chosen event:**
+
+```bash
+sf data query \
+  --query "SELECT Id, TriggerType FROM DevopsPipelineStageTrigger WHERE RelatedRecordId = '<stageId>' AND TriggerType = '<event>'" \
+  --target-org <doce-org-alias> --json
+```
+
+> For a `Review` gate the trigger is pipeline-level — use `RelatedRecordId = '<pipelineId>'` with `TriggerType = 'Review'` instead. Record the returned Id as `<triggerId>`.
+
+**0b — Find the suite-stage row for the target suite on that trigger:**
+
+```bash
+sf data query \
+  --query "SELECT Id, TestSuiteId, TestSuite.Name, IsQualityGateEnabled, DevopsQualityGateId FROM DevopsTestSuiteStage WHERE DevopsPipelineStageTriggerId = '<triggerId>'" \
+  --target-org <doce-org-alias> --json
+```
+
+Match the row whose `TestSuite.Name` is the suite the user named; its `Id` is `<testSuiteStageId>`.
+
+- If **no** `DevopsTestSuiteStage` row matches (the suite isn't assigned to that trigger), stop and report it — the suite must be assigned first via `dx-devops-test-suite-assignments-configure`. Do **not** fabricate a `testSuiteStageId` or proceed.
+- If the matched row already has `IsQualityGateEnabled = true`, tell the user a gate is already linked and confirm whether to replace it before continuing.
+
+## Rule types
+
+| Type | Description | Threshold |
+|---|---|---|
+| `PASS_PERCENTAGE` | Minimum % of tests that must pass | Required (0–100) |
+| `SEVERITY` | Maximum allowed severity level of failures | Required (numeric, e.g. 1–5) |
+| `ESSENTIAL` | All essential tests must pass | Not required |
+
+---
+
+## MANDATORY IMPACT PREVIEW
+
+**Before executing any commands**, show the user this preview and wait for explicit confirmation:
+
+> "Here's what this quality gate will enforce on `<stageName>`:
+> - Rule: `<type>` — `<description>`
+> - Threshold: `<value>`
+> - Affected pipelines: `<list>`
+>
+> Confirm to apply?"
+
+**Never proceed past this point without showing the impact preview first and receiving explicit confirmation.**
+
+## Confirmation gate
+
+Only proceed after the user has explicitly confirmed (e.g., "yes", "confirm", "go ahead"). If the user declines or does not confirm, stop and do not execute any commands.
+
+---
+
+## Step 1 — Create the gate record
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/qualityGate" \
+  --method POST \
+  --body '{"name": "<gateName>"}' \
+  --target-org <doce-org-alias>
+```
+
+Extract `qualityGateId` from the response.
+
+## Step 2 — Create each rule as an sObject record
+
+Rules are not accepted in the Connect API payload — create them as `DevopsQualityGateRule` records directly. Only create rules the user has requested. `ESSENTIAL` has no threshold.
+
+```bash
+sf data create record \
+  --sobject DevopsQualityGateRule \
+  --values "DevopsQualityGateId='<qualityGateId>' Rule='PASS_PERCENTAGE' Threshold=<value>" \
+  --target-org <doce-org-alias> --json
+
+sf data create record \
+  --sobject DevopsQualityGateRule \
+  --values "DevopsQualityGateId='<qualityGateId>' Rule='ESSENTIAL'" \
+  --target-org <doce-org-alias> --json
+
+sf data create record \
+  --sobject DevopsQualityGateRule \
+  --values "DevopsQualityGateId='<qualityGateId>' Rule='SEVERITY' Threshold=<value>" \
+  --target-org <doce-org-alias> --json
+```
+
+## Step 3 — Link the gate to the suite stage
+
+Update the `DevopsTestSuiteStage` record to link the new gate:
+
+```bash
+sf data update record \
+  --sobject DevopsTestSuiteStage \
+  --record-id <testSuiteStageId> \
+  --values "IsQualityGateEnabled=true DevopsQualityGateId='<qualityGateId>'" \
+  --target-org <doce-org-alias> --json
+```
+
+---
+
+## On success
+
+> "Quality gate `<gateName>` created with `<N>` rule(s) and assigned to `<suiteName>` on `<stageName>`."
+
+## Note
+
+To *re-run* an existing gate after meeting its threshold, that is **not** this mode — use `dx-devops-test-suite-run` (retrigger mode). To assign or map suites to stages first, use `dx-devops-test-suite-assignments-configure`.
+
+See `references/error-handling.md` for status-code responses.

package/skills/dx-devops-test-pipeline-configure/references/configuring-test-provider.md

@@ -0,0 +1,80 @@
+# Mode A — Configure a Test Provider
+
+Configures an *Available* (not-yet-configured) test provider on a DevOps Center pipeline, making its test suites available for assignment to pipeline stages.
+
+**Confirmation required:** Yes — explicit confirmation before the provider is configured.
+
+## Inputs
+
+| Variable | Source |
+|---|---|
+| `doce-org-alias` | Prerequisite 1 |
+| `pipelineId` | Prerequisite 4 (pipeline selection) |
+| `testProviderId` | Resolved by fetching the pipeline's test providers (Step 1 below) |
+
+Prerequisite 5 (stage) is **not** required — providers are configured at the pipeline level.
+
+---
+
+## Step 1 — Fetch test providers to resolve the provider ID
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all" \
+  --target-org <doce-org-alias>
+```
+
+Each provider entry includes `testProviderId`, `testProviderName`, and a status (Configured vs. Available). Present a short summary grouped by status:
+
+```text
+Test providers for <pipelineName>:
+
+✓ Configured:
+- Code Analyzer (63 suites)
+- Apex Unit Tests (5 suites)
+
+Available (not yet configured):
+- Flow Tests
+```
+
+- **Only an Available provider can be configured.** If the pipeline has no available providers, report that and stop — do NOT fabricate a provider or ID.
+
+### If the named provider is already Configured
+
+Do **not** present the confirmation gate and do **not** POST to the configure endpoint (Steps 2–3) — that would create a duplicate `DevopsPipelineTestProvider`. Instead:
+
+1. State plainly that the provider is already configured, including its synced suite count and last-sync time if returned (e.g. *"Flow Tests is already configured on `<pipelineName>` with 3 suites synced (last sync 2026-06-23)."*).
+2. Diagnose the user's actual goal and redirect **by name**:
+   - If the user says the provider's **suites don't appear when assigning tests to a stage**, this is a **stage-assignment gap, not a provider-configuration gap** — the suites already exist at the pipeline level; they just need to be linked to the stage. Redirect to **`dx-devops-test-suite-assignments-configure`**.
+   - If the user expects **newly created suites** that aren't yet synced, use **Mode B — Sync a configured provider** (`references/syncing-test-providers.md`) to pull them in.
+3. Do not loop back to configuring — finish cleanly after the explanation and redirect.
+
+## Step 2 — Confirmation gate
+
+**Required — do not call the API before the user confirms.**
+
+> "I'll configure `<testProviderName>` on the `<pipelineName>` pipeline. This will make its suites available for assignment to stages. Confirm?"
+
+Do not proceed until the user gives an affirmative response.
+
+## Step 3 — Configure the provider
+
+On confirmation, call the configure endpoint with the provider ID:
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devops/pipeline/<pipelineId>/testProvider" \
+  --method POST \
+  --body '{"testProviderId": "<testProviderId>"}' \
+  --target-org <doce-org-alias>
+```
+
+## On success
+
+> "Provider `<testProviderName>` is now configured on the `<pipelineName>` pipeline. Its suites are available for assignment to stages."
+
+Newly configured suites can then be assigned to stages with `dx-devops-test-suite-assignments-configure`.
+
+---
+
+See `references/gotchas.md` for the duplicate-provider trap and `references/error-handling.md` for status-code responses.

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

@@ -0,0 +1,39 @@
+# Error Handling — All Modes
+
+Never expose raw API error messages, stack traces, or JSON payloads to the user. Map response status codes to plain-language messages.
+
+## Mode A — Configure a test provider
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The request was invalid. Check that the provider ID and pipeline ID are correct." |
+| 403 | "You don't have permission to configure test providers on this pipeline." |
+| 404 | "The pipeline or test provider was not found." |
+| 409 | "That provider appears to already be configured on this pipeline. To pick up new suites, re-sync it instead." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Mode B — Sync a configured provider
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The sync request was invalid. Check that the provider ID and pipeline ID are correct." |
+| 403 | "You don't have permission to sync test providers on this pipeline." |
+| 404 | "The pipeline or test provider was not found." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Mode C — Configure a quality gate
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The quality gate configuration is invalid. Check that all rule types and thresholds are correct." |
+| 403 | "You don't have permission to configure quality gates on this org." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+## Prerequisite / environment errors
+
+| Error condition | Response |
+|---|---|
+| `sf org list` fails entirely | "Could not reach the Salesforce CLI. Make sure `sf` is installed and on your PATH." |
+| `sf org display` returns auth error | Surface plain-language re-auth instructions. Do not expose the raw error. |
+| `DevopsPipeline` query fails with 5xx | "The DevOps Center org is returning a server error. Try again in a few minutes." |
+| Any check throws unexpectedly | "Something went wrong checking prerequisites. Error: [plain summary]. Let's try again — or resolve it manually and let me know when ready." |

package/skills/dx-devops-test-pipeline-configure/references/gotchas.md

@@ -0,0 +1,37 @@
+# Critical Gotchas
+
+## Duplicate provider configuration (the big one)
+
+`POST /connect/devops/pipeline/<pipelineId>/testProvider` **creates a new provider configuration record** (`DevopsPipelineTestProvider`). Use it ONLY to configure a provider for the **first time** (Mode A).
+
+To re-sync an already-configured provider for new suites, use `POST /connect/devops/sync` (Mode B). Calling the configure endpoint on an already-configured provider produces **duplicate** `DevopsPipelineTestProvider` records.
+
+**Decision tree:**
+
+- Provider is **Available** → configure via `POST .../pipeline/<id>/testProvider` (Mode A).
+- Provider is **Configured**, new suites missing → sync via `POST /connect/devops/sync` (Mode B).
+- Provider is **Configured**, suites missing only when assigning to a stage → stage-assignment gap; redirect to `dx-devops-test-suite-assignments-configure`.
+
+## API name differences
+
+| Issue | Resolution |
+|---|---|
+| `DevopsPipeline` query returns empty | DevOps Center not installed on the target org, or wrong org alias — ask the user to verify |
+| `DevopsWorkItem` sObject not supported | Use `WorkItem` (no namespace) — the correct API name for this org version |
+| `sf plugins` doesn't match `agentforce` | The installed plugin is `@salesforce/plugin-agent` — match on `plugin-agent` too |
+
+## Trigger-type rules
+
+| Issue | Resolution |
+|---|---|
+| Review trigger is pipeline-level, not stage-level | Query `DevopsPipelineStageTrigger` where `TriggerType = 'Review'` and `RelatedRecordId = <pipelineId>` |
+| Connect API `testSuites` returns empty with `?stageId=` | Use `?triggerId=<reviewTriggerId>` — `stageId` only works for stage-level triggers |
+
+## Endpoint families
+
+- **Configure provider:** `POST /connect/devops/pipeline/<pipelineId>/testProvider`
+- **Sync provider:** `POST /connect/devops/sync`
+- **List providers:** `GET /connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all`
+- **Quality gate:** `POST /connect/devopstesting/qualityGate`
+
+Note the `devops` vs `devopstesting` path segment differs between sync/configure and the listing/quality-gate endpoints — copy them exactly.

package/skills/dx-devops-test-pipeline-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/dx-devops-test-pipeline-configure/references/syncing-test-providers.md

@@ -0,0 +1,69 @@
+# Mode B — Sync a Configured Provider
+
+Re-syncs an already-*Configured* test provider on a DevOps Center pipeline so that suites added to the provider since it was last configured become available for assignment to stages.
+
+**Confirmation required:** Yes — explicit confirmation before the sync is triggered.
+
+## Inputs
+
+| Variable | Source |
+|---|---|
+| `doce-org-alias` | Prerequisite 1 |
+| `pipelineId` | Prerequisite 4 (pipeline selection) |
+| `testProviderId` | Resolved by fetching the pipeline's test providers (Step 1 below) |
+
+Prerequisite 5 (stage) is **not** required — providers are synced at the pipeline level.
+
+---
+
+## Step 1 — Fetch test providers to resolve the provider ID
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all" \
+  --target-org <doce-org-alias>
+```
+
+Each provider entry includes `testProviderId`, `testProviderName`, and a status (Configured vs. Available). Present a short summary grouped by status (same format as Mode A).
+
+- **Only a Configured provider can be synced.** If the user names an *Available* (not-yet-configured) provider, explain it must be configured first — use **Mode A** (`references/configuring-test-provider.md`).
+- If the pipeline has no configured providers, report that and stop — do NOT fabricate a provider or ID.
+
+## Step 2 — Confirmation gate
+
+**Required — do not call the API before the user confirms.**
+
+> "I'll re-sync `<testProviderName>` on the `<pipelineName>` pipeline to pick up any new suites. Confirm?"
+
+Do not proceed until the user gives an affirmative response.
+
+## Step 3 — Trigger the sync
+
+On confirmation, call the sync endpoint with the provider ID(s) and pipeline ID:
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devops/sync" \
+  --method POST \
+  --body '{
+    "testProviderIds": ["<testProviderId>"],
+    "pipelineId": "<pipelineId>"
+  }' \
+  --target-org <doce-org-alias>
+```
+
+`testProviderIds` is a list — multiple configured providers can be synced in one call.
+
+## On success
+
+> "Provider `<testProviderName>` sync started. The operation is running asynchronously — new suites will be available shortly."
+
+The sync runs asynchronously; newly synced suites can then be assigned to stages with `dx-devops-test-suite-assignments-configure`.
+
+---
+
+## Critical gotcha
+
+**Do NOT use** `POST /connect/devops/pipeline/<pipelineId>/testProvider` to sync — that endpoint **creates a new provider configuration** and will result in duplicate `DevopsPipelineTestProvider` records. Sync only via `POST /connect/devops/sync`. See `references/gotchas.md`.
+
+See `references/error-handling.md` for status-code responses.

package/skills/dx-devops-test-suite-assignments-configure/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: dx-devops-test-suite-assignments-configure
+description: "Recommends and manages DevOps Center test suite assignments for pipeline stages. Mode A analyzes a commit diff against assigned suite metadata to recommend relevant existing suites and flag coverage gaps (pure reasoning). Modes B-D assign a single suite, bulk-map multiple suites with a mandatory impact preview, or add/remove test classes with governance rules, via the testSuiteStages Connect API. Use this skill to recommend suites for a commit, assign or map suites to stages, or add/remove tests in a suite. TRIGGER when: the user asks which suites to run for a commit/diff or what covers their changes; a suite is unlinked and the user wants it assigned; the user wants to configure suite-to-stage mappings, assign multiple suites, or add/remove/sync tests in a suite. DO NOT TRIGGER when: configuring or syncing a test provider (use dx-devops-test-pipeline-configure), running suites (use dx-devops-test-suite-run), or authoring/running tests directly (use generating-apex-test or running-apex-tests)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Configure DevOps Center Suite Assignments
+
+Recommends which existing test suites to run for a change, and manages how suites are assigned and mapped to pipeline stages. These operations share the same suite-stage metadata: a recommendation surfaces relevant suites and flags gaps, and those gaps lead directly into assignment.
+
+> **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. Never search the filesystem for suite configuration. Always query the org with `sf data query` or `sf api request rest`.
+
+---
+
+## Step 1 — Run prerequisites first (always)
+
+Run the prerequisite checks in `references/prerequisite-checks.md` before any query or system call. On any failure, surface the plain-language message and stop.
+
+- **Mode A (recommend):** Prerequisites 1–4 (org login, plugin, DevOps Center org auth, pipeline identified). No stage required — recommendation reads the pipeline-level Review trigger.
+- **Modes B–D (assign/map/classes):** Prerequisites 1–4 **and** Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, and `stageId`.
+
+---
+
+## Step 2 — Select the mode
+
+| If the user wants to… | Mode | Follow |
+|---|---|---|
+| Know **which suites to run** for a commit/diff, or what covers their changes | **A — Recommend suites** | `references/recommendation-logic.md` |
+| Assign **one** suite to a stage as a one-off | **B — Assign a single suite** | `references/suite-assignment-modes.md` |
+| **Bulk-map** multiple suites to a stage as a testing strategy | **C — Map multiple suites** | `references/suite-assignment-modes.md` |
+| **Add/remove** individual test classes within a suite assignment | **D — Add/remove classes** | `references/suite-assignment-modes.md` |
+
+Mode A is pure reasoning (no writes). Modes B–D mutate org state via the same `testSuiteStages` endpoint (`references/api-endpoint.md`).
+
+**How A feeds B–D:** When recommendation flags a relevant suite that is *not assigned* to the stage, that gap is the input to Mode B/C. When it flags a *new method with no suite coverage*, direct the developer to author tests manually (v1 constraint — never suggest generating tests here).
+
+---
+
+## Step 3 — Governance & confirmation (Modes B–D)
+
+Modes B–D **must** confirm before any write:
+
+- **Mode B** — single confirmation prompt naming the suite, stage, and event.
+- **Mode C** — a **mandatory impact-preview table** (Suite / Stage / Event / Action) before the confirmation gate.
+- **Mode D** — re-present the final test list before confirming. **Rejected tests must be EXCLUDED from the payload.** If tests were modified during review, re-present the final list before requesting confirmation. Never call without explicit approval.
+
+Do not call the API until the user gives an affirmative response. If the user declines, stop without writing. Full wording for each gate is in `references/suite-assignment-modes.md`.
+
+Mode A (recommendation) makes no writes and needs no confirmation gate.
+
+---
+
+## Step 4 — Execute and report
+
+Follow the chosen reference file:
+
+- `references/recommendation-logic.md` — Mode A: diff classification, provider matching, ranking, gap flagging, output format.
+- `references/suite-assignment-modes.md` — Modes B–D: inputs, confirmation wording, success messages.
+- `references/api-endpoint.md` — the shared `testSuiteStages` POST payload schema (Modes B–D).
+- `references/error-handling.md` — status-code → plain-language tables.
+
+Never expose raw API errors, stack traces, or JSON to the user.
+
+---
+
+## Related skills
+
+- **`dx-devops-test-pipeline-configure`** — if the suite you want to assign doesn't appear yet, configure or re-sync the provider; also configures quality gates on a stage after mapping.
+- **`dx-devops-test-suite-run`** — execute a recommended/assigned suite on a stage.
+- **`dx-devops-test-failures-analyze`** — analyze failures and improvement suggestions for the tests within a suite.

package/skills/dx-devops-test-suite-assignments-configure/references/api-endpoint.md

@@ -0,0 +1,30 @@
+# API Endpoint — testSuiteStages (Modes B–D)
+
+All three assignment modes (B, C, D) use the same Connect API 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"}
+  ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `pipelineStageId` | string | The pipeline stage ID (from Prerequisite 5) |
+| `event` | string | `Pre-Promote`, `Post-Promote`, or `Review` |
+| `assignments` | array | One or more `{testSuiteId, action}` entries — `action` is `add` or `remove` |
+
+- **Mode B** sends a single `add` assignment.
+- **Mode C** sends multiple `add`/`remove` entries in one call (bulk mapping).
+- **Mode D** sends `add`/`remove` entries for the classes/suites being synced — rejected tests excluded.