@salesforce/afv-skills 1.25.0 → 1.26.0

package/package.json

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

package/skills/dx-devops-test-failures-analyze/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: dx-devops-test-failures-analyze
+description: "Analyzes DevOps Center test failures and Code Analyzer violations in plain language — failure category, offending file/class/method/line, rule violated, fix direction, and prioritized improvement suggestions (test-code vs production-code) — then optionally creates a tracked fix WorkItem on explicit request. Analysis is pure reasoning; work-item creation is a confirmation-gated write. Use this skill to explain failures or improvement suggestions, translate Code Analyzer violations, or track a fix as a work item. TRIGGER when: a run failed and the user wants root cause; a quality gate failure needs explaining; violations need translating; the user shares a failure payload and asks how to address it; wants to strengthen tests; or wants to create a fix work item, log a remediation, or assign a failure. 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"
+---
+
+# Analyze DevOps Center Test Failures
+
+Parses a test failure or Code Analyzer violation payload, explains it in plain language, produces prioritized improvement suggestions, and — only on explicit user request — creates a tracked fix work item. Parts 1–2 are pure reasoning (no writes); Part 3 is an optional, confirmation-gated write.
+
+**Never expose raw JSON, stack traces, or internal Salesforce error codes to the user.** Always translate to file name, method, line, and plain description.
+
+---
+
+## Prerequisites
+
+- **Parts 1–2 (analysis):** If the failure payload is already in context, no prerequisites are needed — this is pure reasoning. If you must fetch the payload yourself, run prerequisites (`references/prerequisite-checks.md`, Prereqs 1–4) and obtain the execution result via `dx-devops-test-suite-run` (its polling step).
+- **Part 3 (work item):** Run Prerequisites 1–4. You also need a `DevopsProjectId` to file under and an `OwnerId` (assignee). See `references/work-item-creation.md`.
+
+---
+
+## Part 1 — Classify and explain each failure
+
+Determine the failure category, then for each failure extract and translate to plain language: offending file/class, method, line number, the rule or assertion violated, and a fix direction (without writing code). Group failures by category if more than one.
+
+| 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`) |
+| Timeout | Test exceeded execution time limit |
+| Compile error | Class failed to compile |
+
+**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>
+```
+
+Full category/pattern tables and Code Analyzer rule translations: `references/failure-categories.md` and `references/code-analyzer-violations.md`.
+
+**Empty / 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 or suggestions.
+
+---
+
+## Part 2 — Improvement suggestions
+
+Run this **after execution completes with failures**, not on static source. For each failed test, reason over the failure message (the primary signal) to identify what the test is not handling, then produce a specific, actionable suggestion and a **fix location** (Test vs Production code). The full failure-pattern → suggestion mapping is in `references/failure-categories.md`.
+
+```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
+
+Overall: <N> improvement(s) across <M> failed test(s).
+```
+
+Do not rewrite the test — only describe what needs to change and why. **Fix location: Production code** indicates a code defect exposed by a sound test (track separately, not a test-quality blocker). **Fix location: Test** indicates the test needs hardening (setup, assertions, edge cases).
+
+---
+
+## Part 3 — Create a fix work item (optional, on request only)
+
+Trigger only when the user wants to create a fix work item, log a remediation, or assign a failure to a developer. This is a **write** operation with a mandatory confirmation gate. Follow `references/work-item-creation.md` for inputs, the subject/assignee/project confirmation gate, the `sf data create record --sobject WorkItem` call, and error handling.
+
+> Use `WorkItem` (no namespace) — `DevopsWorkItem` is not a supported sObject in this org version.
+
+If no `DevopsProject` exists in the org, report that the work item cannot be created until a project is set up — do NOT fabricate a project or proceed.
+
+---
+
+## Related skills
+
+- **`dx-devops-test-suite-run`** — produces the failure payload (via its polling step) that feeds this skill.
+- **`dx-devops-test-suite-assignments-configure`** — assign/strengthen the suites whose tests are failing.
+- **`generating-apex` / `generating-apex-test`** — to actually write fix code or new test classes (out of scope here).

package/skills/dx-devops-test-failures-analyze/references/code-analyzer-violations.md

@@ -0,0 +1,26 @@
+# Code Analyzer Violations
+
+For each Code Analyzer violation, always include:
+
+- The rule name translated to plain English
+- The exact line number
+- The fix direction (without writing code)
+
+## Rule-name translations (examples)
+
+| Rule name | Plain-language meaning | Fix direction |
+|---|---|---|
+| `ApexCRUDViolation` | A SOQL query or DML was made without checking object-level permissions first | Add a `Schema.sObjectType.<Object>.isAccessible()` (or `isCreateable`/`isUpdateable`) check before the operation |
+| `ApexSharingViolations` | A class that performs data access does not declare sharing enforcement | Add `with sharing` (or an explicit `without sharing` with justification) to the class declaration |
+| `ApexDangerousMethods` | A dangerous or disallowed method was used | Replace with the safe, supported alternative |
+| `EmptyCatchBlock` | An exception is being swallowed silently | Log or handle the exception rather than leaving the catch block empty |
+
+When a rule isn't in this table, translate it from its name and message into a plain-language description of what was violated, then give the fix direction.
+
+## 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.
+
+## Fix location for violations
+
+Code Analyzer violations almost always indicate a **production-code** fix — the static-analysis rule is flagging the code under test, not the test itself. Flag these as **Fix location: Production code** and track them separately from test-quality issues.

package/skills/dx-devops-test-failures-analyze/references/failure-categories.md

@@ -0,0 +1,85 @@
+# Failure Categories & Improvement Mapping
+
+## Inputs required per failed test
+
+- Test method name
+- Failure message (the assertion error or exception text)
+- Failure category (assertion failure, unhandled exception, timeout, compile error)
+
+## Category table
+
+| 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 |
+
+## Per-failure extraction (Part 1)
+
+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)
+
+Group failures by category if more than one.
+
+## Failure-pattern → improvement suggestion (Part 2)
+
+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 permissions — run as a user with the 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 production code, not the test |
+
+## Producing 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 **production code** (test is correct, code under test is broken)
+
+Do not rewrite the test — only describe what needs to change and why.
+
+## Test fix vs. production-code fix
+
+- **Fix location: Production code** — a code defect exposed by a sound test. Should NOT block suite promotion on test-quality grounds; track separately as a production defect.
+- **Fix location: Test** — the test needs hardening: missing setup, wrong assertions, inadequate coverage of edge cases (null inputs, bulk record volumes, mixed permission contexts, governor-limit boundaries).
+
+## Output formats
+
+**Part 1 — failure summary:**
+
+```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>
+```
+
+**Part 2 — improvement suggestions:**
+
+```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
+
+Overall: <N> improvement(s) across <M> failed test(s).
+```

package/skills/{checking-devops-prerequisites/SKILL.md → dx-devops-test-failures-analyze/references/prerequisite-checks.md}

@@ -1,22 +1,16 @@
----
-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
+# Prerequisite Checks — Shared DevOps Center Gate
 
-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.
+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`.
 
-## How other skills use this
+**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.
 
-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.
+## 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.
@@ -94,7 +88,7 @@ sf data query \
 
 ## Prerequisite 5 — Pipeline stage identified (conditional)
 
-Run **only** when the calling skill operates on a specific stage.
+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:
 
@@ -115,27 +109,4 @@ sf data query \
 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 |
+- **Deferred:** not required until the operation needs it

package/skills/{creating-fix-work-item/SKILL.md → dx-devops-test-failures-analyze/references/work-item-creation.md}

@@ -1,14 +1,10 @@
----
-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 platform-apex-generate)."
-metadata:
-  version: "1.0"
-  minApiVersion: "67.0"
----
+# Part 3 — Create a Fix Work Item
+
+Creates a DevOps Center `WorkItem` to track a fix for a test failure or Code Analyzer violation. This is an **optional write**, triggered only when the user asks to create a fix work item, log a remediation, or assign a failure to a developer.
 
 ## 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.
+Run Prerequisites 1–4 (`references/prerequisite-checks.md`). You need `doce-org-alias`, a `DevopsProjectId` to file under, and an `OwnerId` (assignee). If no `DevopsProject` exists, surface that the work item cannot be created until a project exists — do NOT fabricate a project or work item.
 
 ## Inputs required before creating
 
@@ -16,7 +12,7 @@ Load `checking-devops-prerequisites` first — Prerequisites 1–4. You need `do
 |---|---|
 | `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. |
+| `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. Default to the requesting user when no assignee is specified; ask only if the username is unknown and no default applies. |
 | `doce-org-alias` | Established in Prerequisites |
 
 ## Confirmation gate
@@ -46,7 +42,7 @@ sf data create record \
 
 ## On success
 
-Parse the returned `id` from the result and confirm:
+Parse the returned `id` and confirm:
 
 > "Fix work item created (`<id>`): `<subject>`. Assigned to `<assigneeName>` in the `<projectName>` project."
 
@@ -61,6 +57,6 @@ Never expose raw API error messages. Map errors to plain-language responses:
 | `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
+## No-project case
 
-- `analyzing-test-failures` — provides the failure analysis and improvement suggestions that motivate creating a fix work item
+If the `DevopsProject` query returns 0 records, report clearly that no DevOps Center project exists and the work item cannot be created until one is set up. Do NOT fabricate a project name/ID, do NOT proceed to the confirmation gate or the create command.

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." |