@salesforce/afv-skills 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/analyzing-test-failures/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: analyzing-test-failures
+description: "Parses a DevOps Center test-failure or Code Analyzer violation payload and explains it in plain language — failure category, offending file/class/method/line, rule violated, and fix direction — then gives prioritized test-improvement suggestions (distinguishing test-code from production-code fixes). Pure reasoning: no system calls or code authoring. TRIGGER when: a test run failed and the user wants root cause; a quality gate failure needs explaining; Code Analyzer violations need translating to plain language; the user shares a failure payload and asks how to address it; tests keep failing and the user wants suggestions; or the user wants to close coverage gaps, strengthen assertions, or fix flaky/weak tests. DO NOT TRIGGER when: the user wants fix code written (use generating-apex) or new test classes authored (use generating-apex-test)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# analyzing-test-failures
+
+**Type:** Pure reasoning — no system calls, no code authoring.
+
+**What it does:** Parses a test failure or Code Analyzer violation payload and produces a plain-language explanation, then follows up with concrete, prioritized improvement suggestions per failed test — including whether each fix belongs in the test or in production code. Never exposes raw JSON, stack traces, or API error bodies to the user.
+
+---
+
+## Prerequisites
+
+If you need to fetch the failure payload yourself rather than receiving it, load `checking-devops-prerequisites` first, then use `polling-test-results` to obtain the execution result. If the payload is already in context, no prerequisites are needed — this is pure reasoning.
+
+---
+
+## Inputs
+
+- JSON failure payload provided by the `polling-test-results` skill, or pasted directly into context from a test run or Code Analyzer execution. Specifically required per failed test:
+  - Test method name
+  - Failure message (the assertion error or exception text)
+  - Failure category (assertion failure, unhandled exception, timeout, compile error)
+
+---
+
+## Empty-org / no-data case
+
+If the payload contains no failures or violations, report that clearly (e.g. "No failures found in the provided execution results.") and stop. Do NOT fabricate failures, violations, or improvement suggestions when none are present.
+
+---
+
+## Reasoning steps
+
+1. Determine the failure category:
+
+   | Category | Description |
+   |---|---|
+   | **Assertion failure** | A test assertion failed (expected vs actual mismatch) |
+   | **Exception** | An unhandled exception was thrown |
+   | **Code Analyzer violation** | A static analysis rule was violated (e.g. `ApexCRUDViolation`, `ApexSharingViolations`) |
+   | **Timeout** | Test exceeded execution time limit |
+   | **Compile error** | Class failed to compile |
+
+2. For each failure, extract and translate to plain language:
+   - Offending file and class name
+   - Method name
+   - Line number
+   - What rule or assertion was violated, in plain language
+   - Suggested fix direction (without writing code)
+
+3. Group failures by category if more than one.
+
+---
+
+## Output format
+
+```text
+Test failure summary:
+
+<N> failure(s) found:
+
+1. [<Category>] `<ClassName>.cls` — `<methodName>()` at line <N>
+   What happened: <plain-language description>
+   Rule violated: <ruleName or assertion description>
+   Fix direction: <plain-language suggestion>
+
+2. [<Category>] `<ClassName2>.cls` — `<methodName2>()` at line <N>
+   ...
+```
+
+---
+
+## Code Analyzer violations
+
+For violations, always include:
+- The rule name translated to plain English (e.g. "ApexCRUDViolation" → "A SOQL query was made without checking object-level permissions first")
+- The exact line number
+- The fix direction (e.g. "Add a `Schema.sObjectType.Account.isAccessible()` check before the query")
+
+---
+
+## Plain-language rule
+
+Never paste raw stack traces, JSON payloads, or internal Salesforce error codes into the output. Always translate to file name, method, line, and plain description.
+
+---
+
+## Suggesting improvements
+
+Invoke this section **after test execution completes with failures**, not on static source code. The failure message is the primary signal — it describes what the test expected vs. what actually happened, which directly informs what the test needs to handle better.
+
+### 1 — Read each failure message
+
+For each failed test in the execution result, extract:
+- Test method name
+- Failure message (the assertion error or exception message)
+- Failure category (assertion failure, unhandled exception, timeout, compile error)
+
+### 2 — Infer what the test is not handling
+
+Reason over the failure message to identify the root cause pattern:
+
+| Failure pattern | Improvement suggestion |
+|---|---|
+| `NullPointerException` | The test is not handling null input — add a null check or a test setup that ensures the data exists |
+| `Assertion failed: expected X but was Y` | The expected value in the assertion is wrong or the test data setup does not produce the right state |
+| `List has no rows for assignment` | The test is querying for data that doesn't exist — test setup is incomplete |
+| `System.LimitException: Too many SOQL queries` | The test is hitting governor limits — the code under test or test setup is making too many queries |
+| `Insufficient access rights on cross-reference id` | The test user lacks the required permissions — the test needs to run as a user with appropriate profile/permission set |
+| `DML currently not allowed` | The test is performing DML inside a method called from a context that doesn't allow it |
+| Code Analyzer violation message | The production code violates a specific rule — the test exposed it but the fix is in the production code, not the test |
+
+### 3 — Produce actionable suggestions
+
+For each failure, describe in plain language:
+- What the failure reveals about what the test is not handling
+- What specifically should be added or changed to make the test robust
+- Whether the fix is in the **test** (assertion, setup, permissions) or in the **production code** (the test is correct but the code under test is broken)
+
+Do not rewrite the test. Only describe what needs to change and why.
+
+### Output format for improvements
+
+```text
+Test improvement suggestions based on execution results:
+
+`<testMethodName>()` — [Assertion Failure / Exception / etc.]
+Failure: "<failure message>"
+What this reveals: <plain-language explanation>
+Suggestion: <specific, actionable recommendation>
+Fix location: Test | Production code
+
+`<testMethodName2>()` — [NullPointerException]
+Failure: "Attempt to de-reference a null object"
+What this reveals: The test is calling the method without setting up the required input data
+Suggestion: Add test data setup for <object/field> before calling the method
+Fix location: Test
+
+Overall: <N> improvement(s) across <M> failed test(s).
+```
+
+### Test fix vs. production-code fix
+
+Suggestions flagged as **Fix location: Production code** indicate a code defect exposed by the test — the test logic itself is sound. These should not block suite promotion on the grounds of test quality; they should be tracked separately as production defects.
+
+Suggestions flagged as **Fix location: Test** indicate the test needs to be hardened — missing setup, wrong assertions, inadequate coverage of edge cases (null inputs, bulk record volumes, mixed permission contexts, governor-limit boundaries).
+
+---
+
+## Related skills
+
+- **`polling-test-results`** — obtains the failure payload that feeds into this skill.
+- **`creating-fix-work-item`** — use to create a tracked fix item from the analysis output or to track an approved improvement suggestion as a work item once the user decides to act on it.

package/skills/checking-devops-prerequisites/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: checking-devops-prerequisites
+description: "Validate the environment before any DevOps Center pipeline testing action: confirms an authenticated Salesforce org, the Agentforce DX plugin, an authenticated DevOps Center org, and an identified pipeline (and optionally a pipeline stage). Use this FIRST, internally, from any DevOps testing skill (running a test suite, polling results, syncing tests, configuring or retriggering a quality gate, assigning/mapping suites, creating fix work items, recommending tests, explaining coverage, analyzing failures). TRIGGER when another DevOps testing skill needs to confirm org/pipeline context before a query or system call. DO NOT TRIGGER for non-DevOps-Center work."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Checking DevOps Prerequisites
+
+Shared 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`.
+
+## How other skills use this
+
+Every DevOps testing skill loads this skill first and runs Prerequisites 1–4 in order. Prerequisite 5 (stage) is run **only** when the calling skill operates on a specific pipeline stage (running/retriggering a suite, syncing, configuring a gate, mapping a suite). The calling skill passes back the resolved `doce-org-alias`, `pipelineId`, and (when applicable) `stageId` to use in its own commands.
+
+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 calling skill operates on a specific stage.
+
+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 a calling skill needs it
+
+---
+
+## Error Handling
+
+| 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." |
+
+Never expose raw API errors, stack traces, or JSON error payloads to the user.
+
+## Gotchas
+
+| 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 |
+| 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 |
+| `sf plugins` doesn't match `agentforce` | The installed plugin is `@salesforce/plugin-agent` — match on `plugin-agent` too |

package/skills/configuring-quality-gate/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: configuring-quality-gate
+description: "Creates a DevOps Center quality gate with associated rules (PASS_PERCENTAGE, SEVERITY, ESSENTIAL) and links it to a pipeline-stage suite assignment, after showing a mandatory impact preview and obtaining explicit confirmation. Use this skill when a user wants to set or configure a quality gate, change a coverage threshold, or establish testing benchmarks on a pipeline stage. TRIGGER when: the user wants to set/configure a quality gate, change a coverage threshold, or set testing benchmarks on a stage. DO NOT TRIGGER when: only re-running an existing gate (use running-devops-test-suite in retrigger mode)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4 AND Prerequisite 5 (stage). You need `doce-org-alias`, `pipelineId`, `stageId`, and the target `DevopsTestSuiteStage` record Id.
+
+## Inputs required
+
+| Input | Source |
+|---|---|
+| `name` | User-provided name for the quality gate |
+| `rules` | List of `{type, threshold?}` — see rule types below |
+| `doce-org-alias` | Established in Prereq 1 |
+| `testSuiteStageId` | Target `DevopsTestSuiteStage` record Id (Prereq 5) |
+
+## 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 with the steps below 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 a 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
+
+Confirm to the user:
+> "Quality gate `<gateName>` created with `<N>` rule(s) and assigned to `<suiteName>` on `<stageName>`."
+
+## Error handling
+
+Never expose raw API errors. Use the following responses:
+
+| Status | Response |
+|---|---|
+| 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." |
+
+---
+
+## Related skills
+
+- To re-run a gate after meeting threshold, use `running-devops-test-suite` (retrigger mode).
+- To assign or map suites to stages, use `managing-suite-assignments`.

package/skills/configuring-test-provider/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: configuring-test-provider
+description: "Configures an available test provider (e.g. Apex Unit Tests, Code Analyzer, Flow Tests, Provar) on a DevOps Center pipeline via the Connect API, after explicit user confirmation, so the provider's test suites become available for assignment to pipeline stages. Takes a pipelineId and a testProviderId. Use this skill when a provider is available on the pipeline but not yet configured and the user wants to enable it. TRIGGER when: the user wants to configure, enable, set up, or add a test provider on a pipeline, or wants a not-yet-configured provider's suites to become available. DO NOT TRIGGER when: re-syncing an already-configured provider to pick up new suites (use syncing-test-providers), or assigning existing suites to a stage (use managing-suite-assignments)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Configuring a Test Provider
+
+Configures an available 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.
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — 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, not the stage level.
+
+| Variable | Source |
+|---|---|
+| `doce-org-alias` | Established in Prerequisite 1 |
+| `pipelineId` | Identified in Prerequisite 4 (pipeline selection) |
+| `testProviderId` | Resolved by fetching the pipeline's test providers (below) |
+
+---
+
+## Step 1 — Fetch test providers to resolve the provider ID
+
+Get all test providers for the pipeline so you can resolve the `testProviderId` and confirm which providers are still available to configure:
+
+```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 **`managing-suite-assignments`**.
+   - If the user expects **newly created suites** that aren't yet synced, redirect to **`syncing-test-providers`** (re-sync via `POST /connect/devops/sync`) 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 `managing-suite-assignments`.
+
+---
+
+## Critical gotcha
+
+This `POST .../pipeline/<pipelineId>/testProvider` endpoint **creates a new provider configuration record** (`DevopsPipelineTestProvider`). Use it ONLY to configure a provider for the first time. To re-sync an already-configured provider for new suites, use `syncing-test-providers` (`POST /connect/devops/sync`) — calling this configure endpoint on an already-configured provider produces **duplicate** `DevopsPipelineTestProvider` records.
+
+## Error Handling
+
+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 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." |
+
+---
+
+## Related skills
+
+- **`checking-devops-prerequisites`** — loaded first to establish org and pipeline context.
+- **`syncing-test-providers`** — once a provider is configured, use this to re-sync it later and pull in newly added suites.
+- **`managing-suite-assignments`** — after configuring a provider, use this to assign or map its suites to a pipeline stage.
+- **`recommending-devops-tests`** — to recommend which of the newly available suites to run.

package/skills/creating-fix-work-item/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: creating-fix-work-item
+description: "Creates a DevOps Center WorkItem to track a fix for a test failure or Code Analyzer violation. Before creating anything, it shows a subject/assignee/project preview and requires explicit confirmation. Use this skill when you want to create a fix work item, track a remediation task, or assign a test or analysis failure to a developer. TRIGGER when: the user wants to create a fix work item, log a remediation, or assign a failure to a developer for resolution. DO NOT TRIGGER when: writing the fix code itself (use generating-apex)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4. You need `doce-org-alias`, the `DevopsProjectId` to file under, and an `OwnerId` (assignee). If no DevopsProject exists, surface that the work item cannot be created until a project exists.
+
+## Inputs required before creating
+
+| Input | How to obtain |
+|---|---|
+| `DevopsProjectId` | From the pipeline's associated project — query `DevopsProject WHERE Name = '<projectName>'` on the doce org if not already known |
+| `Subject` | Derived from failure analysis — e.g. "Fix: Missing code-analyzer-v5.yml workflow in blitz-10-06 repository" |
+| `OwnerId` | User ID of the developer to assign to — query `SELECT Id, Name FROM User WHERE Username = '<username>'` on the doce org if not known. Ask the user if the username is unknown. |
+| `doce-org-alias` | Established in Prerequisites |
+
+## Confirmation gate
+
+Before creating the work item, show a summary and wait for explicit confirmation:
+
+> "I'll create a fix work item with the following details:
+> - **Subject:** `<subject>`
+> - **Assigned to:** `<assigneeName>`
+> - **Project:** `<projectName>`
+>
+> Shall I create it?"
+
+Do not proceed until the user confirms.
+
+## Creating the work item
+
+```bash
+sf data create record \
+  --sobject WorkItem \
+  --values "Subject='<subject>' DevopsProjectId='<DevopsProjectId>' OwnerId='<OwnerId>'" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+> **Important:** Use `WorkItem` (no namespace) — `DevopsWorkItem` is not a supported sObject in this org version.
+
+## On success
+
+Parse the returned `id` from the result and confirm:
+
+> "Fix work item created (`<id>`): `<subject>`. Assigned to `<assigneeName>` in the `<projectName>` project."
+
+## Error handling
+
+Never expose raw API error messages. Map errors to plain-language responses:
+
+| Error | Response |
+|---|---|
+| `FIELD_INTEGRITY_EXCEPTION` | "The assignee ID is invalid. Let me look up the correct user ID — what's the developer's username?" |
+| `REQUIRED_FIELD_MISSING` | "A required field is missing. Check that `Subject` and `DevopsProjectId` are both provided." |
+| `INSUFFICIENT_ACCESS` | "Your user doesn't have permission to create work items in this project." |
+| Any other error | "The work item could not be created. Error: `<plain summary>`. Try again or create it manually in DevOps Center." |
+
+## Related skills
+
+- `analyzing-test-failures` — provides the failure analysis and improvement suggestions that motivate creating a fix work item

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/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

package/skills/syncing-test-providers/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: syncing-test-providers
+description: "Re-syncs a configured DevOps Center test provider on a pipeline to pick up new test suites, via the Connect API sync endpoint, after explicit user confirmation. Takes a pipelineId and one or more testProviderIds and triggers an asynchronous re-sync so newly added suites become available for assignment. Use this skill when a test provider (e.g. Apex Unit Tests, Code Analyzer, Flow Tests, Provar) has had suites added since it was last configured and the user wants those suites to show up in DevOps Center. TRIGGER when: the user wants to re-sync a test provider, pull in new suites from a provider, refresh a provider's suite list, or says assigned suites are missing/out of date for a configured provider. DO NOT TRIGGER when: configuring a provider for the first time (that creates a new DevopsPipelineTestProvider configuration), or assigning/mapping existing suites to a stage (use managing-suite-assignments)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Syncing Test Providers
+
+Re-syncs a 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.
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4 (org login, Agentforce DX plugin, DevOps Center org auth, pipeline identified). Prerequisite 5 (stage) is **not** required: providers are synced at the pipeline level, not the stage level.
+
+| Variable | Source |
+|---|---|
+| `doce-org-alias` | Established in Prerequisite 1 |
+| `pipelineId` | Identified in Prerequisite 4 (pipeline selection) |
+| `testProviderId` | Resolved by fetching the pipeline's test providers (below) |
+
+---
+
+## Step 1 — Fetch test providers to resolve the provider ID
+
+Get all test providers configured on the pipeline so you can resolve the `testProviderId` and confirm the provider name with the user:
+
+```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 a Configured provider can be synced.** If the user names an *Available* (not-yet-configured) provider, explain it must be configured first — this skill does not configure providers.
+- 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 `managing-suite-assignments`.
+
+---
+
+## 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`.
+
+## Error Handling
+
+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 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." |
+
+---
+
+## Related skills
+
+- **`checking-devops-prerequisites`** — loaded first to establish org and pipeline context.
+- **`configuring-test-provider`** — use to configure an available provider for the first time; this skill only re-syncs already-configured providers.
+- **`managing-suite-assignments`** — after a sync surfaces new suites, use this to assign or map them to a pipeline stage.
+- **`recommending-devops-tests`** — to recommend which of the newly synced suites to run.