@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/dx-devops-request-status/references/cli-commands.md

@@ -0,0 +1,176 @@
+# DevOps Center Request Status CLI Command Reference
+
+Reference for `sf devops request status` with its JSON output schema and error handling. This is a **read-only** status check — it issues no mutations. The command is keyed on the **request token** returned by `dx-devops-promote` (the promote response).
+
+## Command Summary
+
+| Command | Purpose | Required Flags | Mutates? |
+|---------|---------|---------------|----------|
+| `sf devops request status` | Get the current status of a request by its request token | `-i/--request-token`, `-o/--target-org` | No (read-only) |
+
+**Org authentication** — verify before any command:
+```bash
+sf org display --json
+```
+
+---
+
+## Request Status (Read-Only)
+
+Returns the current status of a request identified by its request token. Safe to run repeatedly — it never changes pipeline state.
+
+```bash
+sf devops request status \
+  --request-token a0B000000000001 \
+  --target-org my-devops-org \
+  --json
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-i, --request-token` | (required) Request token from the promote response. **Field-name note:** the value comes from the promote response's async identifier — observed as `.result.requestId` on a `promote` response (e.g. `{"status":"PROMOTE_IN_PROGRESS","requestId":"0Xt...","promotedWorkitemIds":[...]}`), while `request status` echoes it back as `.result.requestToken`. Capture it robustly: `jq -r '.result.requestId // .result.requestToken // .result.promotionId // .result.asyncOperationId'` |
+| `-o, --target-org` | (required) Username or alias of the target org. Not required if the `target-org` config variable is set |
+| `--api-version` | Override the API version used for API requests made by this command |
+| `--json` | Format output as JSON (always use for headless parsing) |
+| `--flags-dir` | Import flag values from a directory (global flag) |
+
+### Result fields
+
+| Field | Meaning |
+|-------|---------|
+| `.result.id` | Internal record ID of the async operation (e.g. `8MwWt00000DDuPtKAL`) |
+| `.result.status` | **Request-processing** state, UPPERCASE and **operation-prefixed** (`PROMOTE_IN_PROGRESS`, `PROMOTE_SUCCESS`, `DEPLOY_FAILED`, ...). Reports whether the request finished — NOT whether the deploy succeeded. Match on the suffix (see Status Value Vocabulary) |
+| `.result.message` | Human-readable summary (e.g. `"Deployment failed"`, `"Inspection completed successfully"`) |
+| `.result.errorDetails` | **The outcome oracle.** `null` on success; on failure an escaped JSON *string* `{"errorType": "...", "errorMessage": "..."}` |
+| `.result.requestToken` | Echo of the token you queried |
+| `.result.requestCompletionDate` | Completion timestamp, or `null` while still processing / on failure |
+
+> **CRITICAL — two-level semantics.** `.result.status` and the top-level `status` (CLI exit code) can BOTH be success while the underlying operation failed. The authoritative failure signal is a **non-null `.result.errorDetails`**. Always check `errorDetails`, not just `status`.
+
+### JSON Output Schema (in progress)
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "8MwWt00000DDuPtKAL",
+    "status": "IN_PROGRESS",
+    "message": null,
+    "errorDetails": null,
+    "requestToken": "1c07586d-88e1-432c-bcfd-89abc43db874",
+    "requestCompletionDate": null
+  },
+  "warnings": []
+}
+```
+
+### JSON Output Schema (success)
+
+Request finished AND `errorDetails` is `null`:
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "8MwWt00000DDu9lKAD",
+    "status": "SUCCESS",
+    "message": "Inspection completed successfully",
+    "errorDetails": null,
+    "requestToken": "1c07586d-88e1-432c-bcfd-89abc43db874",
+    "requestCompletionDate": "2026-08-17T12:47:18.000+0000"
+  },
+  "warnings": []
+}
+```
+
+### JSON Output Schema (failure — note `status: "SUCCESS"`!)
+
+The request finished (`status: "SUCCESS"`), but the deploy FAILED. `errorDetails` is populated and `message` says so. This is the trap — do not read `status` alone:
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "8MwWt00000DDuPtKAL",
+    "status": "SUCCESS",
+    "message": "Deployment failed",
+    "errorDetails": "{\"errorType\":\"DEPLOYMENT_FAILURE\",\"errorMessage\":\"classes/HelloMCP.cls-meta.xml: Invalid api version:0.0 (classes/HelloMCP.cls-meta.xml)\"}",
+    "requestToken": "708b2286-bbf3-4621-9531-6d94334ff763",
+    "requestCompletionDate": null
+  },
+  "warnings": []
+}
+```
+
+---
+
+## Status Value Vocabulary
+
+`.result.status` reports whether the **request** finished processing (UPPERCASE) and is **operation-PREFIXED** — the value carries the operation name plus a state suffix, e.g. `PROMOTE_IN_PROGRESS`, `PROMOTE_SUCCESS`, `DEPLOY_FAILED`. Match on the **suffix**, never on a bare exact token, so any prefix (`PROMOTE_`, `DEPLOY_`, `VALIDATE_`, ...) is handled:
+
+| Suffix (glob) | Category | Action |
+|--------|----------|--------|
+| `*_NEW` / `*_QUEUED` / `*_PENDING` | Non-terminal | Keep polling |
+| `*_IN_PROGRESS` / `*_STARTED` / `*_RUNNING` | Non-terminal | Keep polling |
+| `*SUCCESS*` / `*SUCCEEDED*` / `*COMPLETED*` | Request finished | **Then check `errorDetails`** — null = operation succeeded; non-null = operation FAILED |
+| `*FAILED*` / `*FAILURE*` / `*ERROR*` / `*CANCELED*` / `*ABORTED*` | Request finished (failure) | Operation failed — report `errorDetails` |
+
+Reaching a terminal `.result.status` is necessary but NOT sufficient for success. The final gate is `.result.errorDetails == null`. Check failure suffixes BEFORE success so a `*_FAILED` never slips through.
+
+Example real value from a `promote` response the token was minted by: `"status": "PROMOTE_IN_PROGRESS"` with `"message": "Promotion started successfully"`.
+
+### Deriving the true outcome deterministically
+
+Do not hand-roll this classification — `scripts/poll-status.sh` owns it so the two-level rule stays consistent across the one-shot and polling paths. For a single check, invoke `--once` and branch on the exit code:
+
+```bash
+scripts/poll-status.sh --once a0B000000000001 my-devops-org
+# 0 = succeeded · 2 = operation failed (status suffix *FAILED*/*ERROR*/*CANCELED*,
+#     or a *SUCCESS* status with non-null errorDetails) · 4 = still processing · 1 = query error
+```
+
+The script glob-matches the operation-prefixed `.result.status` suffix (checking failure suffixes before success so a `*_FAILED` never slips through), then applies the `.result.errorDetails` failure oracle before reporting success.
+
+---
+
+## Error Handling
+
+Distinguish three cases:
+1. **Failed query** — CLI/auth/token problem; top-level `status != 0`. Fix the token or auth.
+2. **Failed operation** — valid query, request finished, but `.result.errorDetails` is non-null (even if `.result.status == "SUCCESS"`). Report the parsed `errorType`/`errorMessage`.
+3. **Still processing** — valid query, `.result.status` non-terminal. Keep polling.
+
+**Request token not found (failed query):**
+```json
+{ "status": 1, "name": "NOT_FOUND", "message": "No request found for the provided token", "exitCode": 1 }
+```
+
+**Missing request-token flag (failed query):**
+```json
+{ "status": 1, "name": "MissingRequiredFlag", "message": "Missing required flag --request-token", "exitCode": 1 }
+```
+
+**Authentication failure (failed query):**
+```json
+{ "status": 1, "name": "NoOrgFound", "message": "No org configuration found for target-org. Run 'sf org login web' to authenticate.", "exitCode": 1 }
+```
+
+**Rate limit / throttle (failed query):**
+```json
+{ "status": 1, "name": "REQUEST_LIMIT_EXCEEDED", "message": "TotalRequests Limit exceeded.", "exitCode": 1 }
+```
+Back off — increase the polling interval; never poll below the 5-second floor.
+
+---
+
+## Authentication Requirements
+
+`sf devops request status` requires:
+
+1. **Authenticated org**: `sf org login web` or JWT auth (for CI)
+2. **DevOps Center enabled**: org must have DOCe provisioned
+3. **Read access** to the request being queried
+
+Auth is the caller's responsibility — this skill contains no auth logic. In CI, use a JWT-authenticated service-account alias with least-privilege scopes.

package/skills/dx-devops-request-status/scripts/poll-status.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# Query a DevOps Center async request and determine the true outcome. Runs a
+# single check (--once) or polls until the request reaches a terminal state.
+# Read-only: issues only `sf devops request status` queries; never mutates.
+#
+# IMPORTANT — two-level semantics:
+#   .result.status is the async REQUEST status (uppercase, operation-prefixed:
+#   PROMOTE_SUCCESS / PROMOTE_IN_PROGRESS / DEPLOY_FAILED / ...). It reports
+#   whether the request finished processing, NOT whether the underlying deploy
+#   succeeded. A request can show a *SUCCESS* status while the deployment itself
+#   FAILED — that failure lives in .result.errorDetails (an escaped JSON string
+#   with errorType/errorMessage). errorDetails is the outcome oracle: non-null
+#   => the operation failed.
+#
+# Usage:
+#   poll-status.sh --once <request-token> <target-org-alias>
+#   poll-status.sh <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]
+#
+# Exit codes:
+#   0  request reached a terminal state AND the operation succeeded (errorDetails null)
+#   1  usage error / missing dependency / status query failed
+#   2  request reached a terminal state BUT the operation failed (errorDetails set,
+#      or status suffix *FAILED*/*ERROR*/*CANCELED*/*ABORTED*)
+#   3  timeout reached before a terminal state (poll mode only)
+#   4  request is still processing (--once mode only — not yet terminal)
+set -euo pipefail
+
+ONCE=0
+if [ "${1:-}" = "--once" ]; then
+  ONCE=1
+  shift
+fi
+
+REQUEST_TOKEN="${1:-}"
+TARGET_ORG="${2:-}"
+INTERVAL="${3:-10}"
+TIMEOUT="${4:-1800}"
+
+usage() {
+  echo "Usage: poll-status.sh [--once] <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]" >&2
+  exit 1
+}
+
+[ -z "$REQUEST_TOKEN" ] && usage
+[ -z "$TARGET_ORG" ] && usage
+
+# Reject non-numeric interval/timeout up front so the bounded loop stays bounded.
+# (Under `set -e`, an arithmetic test against a non-numeric value errors but the
+# loop could otherwise keep running — validate before we ever enter it.)
+is_positive_int() { case "$1" in ''|*[!0-9]*) return 1;; *) [ "$1" -gt 0 ];; esac; }
+if ! is_positive_int "$INTERVAL"; then
+  echo "interval-seconds must be a positive integer, got: $INTERVAL" >&2; usage
+fi
+if ! is_positive_int "$TIMEOUT"; then
+  echo "timeout-seconds must be a positive integer, got: $TIMEOUT" >&2; usage
+fi
+
+command -v sf >/dev/null 2>&1 || { echo "sf CLI not found on PATH" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "jq not found on PATH" >&2; exit 1; }
+
+# Enforce a 5-second minimum polling interval (DOCe API rate limits).
+if [ "$INTERVAL" -lt 5 ]; then INTERVAL=5; fi
+
+# Query once and classify the outcome. Echoes a human-readable line and returns:
+#   0 succeeded, 2 failed (operation), 3 still processing, 1 query error.
+# `.result.status` is operation-PREFIXED — match on the suffix with globs so any
+# prefix is handled. Order matters: check failure suffixes before success so a
+# *_FAILED never falls through to the success arm.
+classify() {
+  local status_json req_status err_details message detail
+  if ! status_json=$(sf devops request status --request-token "$REQUEST_TOKEN" --target-org "$TARGET_ORG" --json 2>/dev/null); then
+    echo "Status query failed for request $REQUEST_TOKEN (org $TARGET_ORG)" >&2
+    return 1
+  fi
+  req_status=$(printf '%s' "$status_json" | jq -r '.result.status // "UNKNOWN"')
+  # errorDetails is an escaped JSON string (or null). "null"/"" => no error.
+  err_details=$(printf '%s' "$status_json" | jq -r '.result.errorDetails // ""')
+  message=$(printf '%s' "$status_json" | jq -r '.result.message // ""')
+
+  case "$req_status" in
+    *FAILED*|*FAILURE*|*ERROR*|*CANCELED*|*CANCELLED*|*ABORTED*)
+      detail=$(printf '%s' "$err_details" | jq -r '"\(.errorType): \(.errorMessage)"' 2>/dev/null || printf '%s' "$err_details")
+      echo "Request $REQUEST_TOKEN failed (request status: $req_status). $message ${detail:+— $detail}" >&2
+      return 2
+      ;;
+    *SUCCESS*|*SUCCEEDED*|*COMPLETED*)
+      # Terminal request state — but a "success" request can still carry a failed
+      # operation. errorDetails is the outcome oracle: non-null => failure.
+      if [ -n "$err_details" ]; then
+        detail=$(printf '%s' "$err_details" | jq -r '"\(.errorType): \(.errorMessage)"' 2>/dev/null || printf '%s' "$err_details")
+        echo "Request $REQUEST_TOKEN failed (request status: $req_status, but errorDetails set). $message ${detail:+— $detail}" >&2
+        return 2
+      fi
+      echo "Request $REQUEST_TOKEN completed successfully (request status: $req_status). $message"
+      return 0
+      ;;
+    *)
+      # Non-terminal (*_IN_PROGRESS / *_PENDING / *_QUEUED / *_STARTED /
+      # *_RUNNING / *_NEW / UNKNOWN) — still processing.
+      echo "Request $REQUEST_TOKEN status: $req_status (still processing). $message"
+      return 3
+      ;;
+  esac
+}
+
+# --once: single query, no waiting. Map "still processing" (3) to exit 4.
+if [ "$ONCE" -eq 1 ]; then
+  set +e; classify; rc=$?; set -e
+  [ "$rc" -eq 3 ] && exit 4
+  exit "$rc"
+fi
+
+# Track WALL-CLOCK time, not accumulated sleep — otherwise the per-poll CLI
+# latency inside classify() is invisible to the timeout and the real deadline
+# drifts past TIMEOUT by the summed query time. $SECONDS is bash's seconds-since-
+# shell-start counter; snapshot it now and measure elapsed against that.
+start=$SECONDS
+while :; do
+  set +e; classify; rc=$?; set -e
+  case "$rc" in
+    0|1|2) exit "$rc" ;;   # terminal (succeeded/failed) or query error — done
+  esac
+  # rc == 3: still processing. Honor timeout-seconds as a true wall-clock cap.
+  elapsed=$((SECONDS - start))
+  if [ "$elapsed" -ge "$TIMEOUT" ]; then
+    echo "Timeout after ${elapsed}s — request $REQUEST_TOKEN still processing" >&2
+    exit 3
+  fi
+  remaining=$((TIMEOUT - elapsed))
+  wait_for=$INTERVAL
+  if [ "$remaining" -lt "$wait_for" ]; then wait_for=$remaining; fi
+  echo "Waiting ${wait_for}s (elapsed ${elapsed}s, timeout ${TIMEOUT}s)..."
+  sleep "$wait_for"
+done

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

@@ -2,17 +2,17 @@
 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 platform-apex-generate) or new test classes authored (use platform-apex-test-generate)."
 metadata:
-  cliTools:
-    - tool: ["sf"]
-      semver: ">=2.67.0"
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "67.0"
   relatedSkills:
     - "dx-devops-test-suite-assignments-configure"
     - "dx-devops-test-suite-run"
     - "platform-apex-generate"
     - "platform-apex-test-generate"
-  version: "1.0"
-  domains: ["Developer Experience"]
-  minApiVersion: "67.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.67.0"
 ---
 
 # Analyze DevOps Center Test Failures

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

@@ -2,16 +2,16 @@
 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:
-  cliTools:
-    - tool: ["sf"]
-      semver: ">=2.67.0"
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "67.0"
   relatedSkills:
     - "dx-devops-test-failures-analyze"
     - "dx-devops-test-suite-assignments-configure"
     - "dx-devops-test-suite-run"
-  version: "1.0"
-  domains: ["Developer Experience"]
-  minApiVersion: "67.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.67.0"
 ---
 
 # Configure DevOps Center Pipeline Testing Infrastructure
@@ -49,7 +49,7 @@ Carry forward the resolved `doce-org-alias`, `pipelineId`, and (Mode C) `stageId
 - 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`.
+**Never POST to the configure endpoint for an already-configured provider** — it creates duplicate `DevopsPipelineTestProvider` records. See `references/gotchas.md`.
 
 ---
 

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

@@ -2,18 +2,18 @@
 name: dx-devops-test-suite-assignments-configure
 description: "Recommends and manages DevOps Center test suite assignments for pipeline stages. Mode A analyzes a commit diff against assigned suite metadata to recommend relevant existing suites and flag coverage gaps (pure reasoning). Modes B-D assign a single suite, bulk-map multiple suites with a mandatory impact preview, or add/remove test classes with governance rules, via the testSuiteStages Connect API. Use this skill to recommend suites for a commit, assign or map suites to stages, or add/remove tests in a suite. TRIGGER when: the user asks which suites to run for a commit/diff or what covers their changes; a suite is unlinked and the user wants it assigned; the user wants to configure suite-to-stage mappings, assign multiple suites, or add/remove/sync tests in a suite. DO NOT TRIGGER when: configuring or syncing a test provider (use dx-devops-test-pipeline-configure), running suites (use dx-devops-test-suite-run), or authoring/running tests directly (use platform-apex-test-generate or platform-apex-test-run)."
 metadata:
-  cliTools:
-    - tool: ["sf"]
-      semver: ">=2.67.0"
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "67.0"
   relatedSkills:
     - "dx-devops-test-failures-analyze"
     - "dx-devops-test-pipeline-configure"
     - "dx-devops-test-suite-run"
     - "platform-apex-test-generate"
     - "platform-apex-test-run"
-  version: "1.0"
-  domains: ["Developer Experience"]
-  minApiVersion: "67.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.67.0"
 ---
 
 # Configure DevOps Center Suite Assignments

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

@@ -2,17 +2,17 @@
 name: dx-devops-test-suite-run
 description: "Runs DevOps Center test suites on a pipeline stage (Pre-Promote, Post-Promote, or Review event) end to end: triggers async execution via the Connect API after an explicit confirmation gate, then polls by runId at provider-specific intervals until it completes, fails, or times out, and hands results to failure analysis. Also retriggers a quality gate after fixes, but only once coverage meets the threshold. Use this skill when a user wants to run, kick off, or launch test suites on a stage, re-run a quality gate, or watch an in-progress run to completion. TRIGGER when: the user wants to run/launch suites on a stage, execute tests before or after promotion, re-run a quality gate after fixing failures, unblock a blocked promotion after adding tests, or poll/watch an in-progress run. DO NOT TRIGGER when: running sf apex run test directly (use platform-apex-test-run), or configuring a NEW gate or threshold (use dx-devops-test-pipeline-configure)."
 metadata:
-  cliTools:
-    - tool: ["sf"]
-      semver: ">=2.67.0"
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "67.0"
   relatedSkills:
     - "dx-devops-test-failures-analyze"
     - "dx-devops-test-pipeline-configure"
     - "dx-devops-test-suite-assignments-configure"
     - "platform-apex-test-run"
-  version: "1.0"
-  domains: ["Developer Experience"]
-  minApiVersion: "67.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.67.0"
 ---
 
 # Run a DevOps Center Test Suite

package/skills/dx-devops-work-item-manage/SKILL.md

@@ -2,6 +2,8 @@
 name: dx-devops-work-item-manage
 description: "Use this skill to manage the full lifecycle of DevOps Center work items — list, create, update, commit changes, perform status transitions, and create pull requests. Update fields like subject, description, and status. Commit and push code changes to work item branches. Create pull requests for work item branches via DevOps Center API. Invoke when the user wants to track, find, create, or update a work item, commit changes to a work item branch, advance a work item's status through the pipeline, or create a pull request for code review. Consolidates sf devops work-item and review operations. DO NOT TRIGGER for promotion or deployment operations, or conflict detection."
 metadata:
+  relatedSkills:
+    - "dx-devops-promote"
   version: "1.0"
   domains: ["Developer Experience"]
   minApiVersion: "58.0"

package/skills/dx-org-manage/references/creating-scratch-org.md

@@ -36,9 +36,12 @@ Determine which approach based on user request:
 
 ### 2. Verify Dev Hub authentication
 
-Check if Dev Hub is authenticated:
+Check if Dev Hub is authenticated (this mirrors the canonical Step 2 in `SKILL.md` — follow that as the source of truth):
 - If `--target-dev-hub` not provided, check `sf config get target-dev-hub`
-- If no Dev Hub configured, prompt user to authenticate: `sf org login web --set-default-dev-hub`
+- If that is empty, enumerate every `sf org list --json` bucket (`devHubs`, `nonScratchOrgs`, `other`, `sandboxes`, `scratchOrgs`) for entries with `isDevHub: true`, then resolve by count:
+  - **Exactly one** → use that username.
+  - **Two or more** → ask the user which one; never pick arbitrarily.
+  - **Zero** → no hub is authenticated. Do NOT run `sf org create` (there is nothing to pass to `--target-dev-hub`). Stop and advise the user to authenticate: `sf org login web --set-default-dev-hub`.
 
 ### 3. Build the command
 

package/skills/dx-org-manage/references/creating-snapshot.md

@@ -49,6 +49,7 @@ Infer from the user's request:
 | Issue | Resolution |
 |-------|------------|
 | Error creating snapshot | Surface the CLI's own error unchanged; the message states what to do next |
+| `@salesforce/plugin-signups does not exist in the registry` | Snapshot commands live in the `signups` plugin, which ships bundled with a normal `sf` install. This error means the CLI environment is incomplete (slim image) or the plugin registry is unreachable (offline). Because the registry is unavailable, `sf plugins install` cannot succeed — do NOT attempt it (it will fail and loop). Surface the error and advise the user to repair their environment from a connected machine: reinstall or update the Salesforce CLI (for example with `sf update`, or a fresh global CLI install through their normal package manager) so the bundled `signups` plugin is present, or run in an image that already includes it. Never run any install/repair from inside the skill. |
 | "No org found for <alias>" error | Source org alias doesn't exist or isn't authenticated — verify with `sf org list` |
 | Snapshot name already exists | Use a different unique name — snapshot names must be unique per Dev Hub |
 | "An error while created the org snapshot" | Generic error — check that source org is a scratch org and still active |

package/skills/dx-org-shape-manage/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: dx-org-shape-manage
+description: "ALWAYS USE THIS SKILL to create, list, or delete org shapes. An org shape is a captured baseline configuration (features, limits, edition, and Metadata API settings) of a source org, without its data or metadata. Use when the user asks to create/make/take an org shape, capture or replicate an org's configuration/edition/limits, list/show/view existing org shapes (including INACTIVE/superseded ones) or their IDs and status, or delete/remove org shapes for a source org. Requires a source org with Dev Hub and Org Shape for Scratch Orgs enabled. DO NOT TRIGGER for creating snapshots or scratch orgs (use dx-org-manage)."
+metadata:
+  version: "1.0"
+  domains: ["Developer Experience"]
+  relatedSkills:
+    - "dx-org-manage"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "orgPref"
+      value: "ScratchOrgManagementPref"
+    - type: "orgPref"
+      value: "ShapeExportPref"
+---
+
+# dx-org-shape-manage
+
+Coordinates the full lifecycle of Salesforce org shapes — **create**, **list**, and **delete** — via `sf org create shape`, `sf org list shape`, and `sf org delete shape`. An org shape captures the baseline setup of a source org (features, limits, edition, and Metadata API settings) **without** its data or metadata.
+
+---
+
+## Tool Restrictions
+
+**Use ONLY the Bash tool** to execute the `sf org ... shape` commands. Do NOT use MCP tools — ignore them completely.
+
+**Output artifacts for eval/testing:** ALWAYS write the command's complete JSON response to a file when an output directory is available. Do NOT ask the user what file to write — this skill defines the filenames. After executing each command: (1) if the user specified an output path (e.g. "write all generated files into folder X"), write there immediately; (2) otherwise run `[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'` to detect the eval directory; (3) write the command's full, unmodified JSON response (including the `status`/`result`/`warnings` wrapper) to `<output-dir>/<filename>` using these filenames: `create-shape-result.json` for shape creation, `list-shapes-result.json` for listing shapes, `list-shapes-inactive-result.json` for the inactive-shapes SOQL query, or `delete-shapes-result.json` for shape deletion. This is the generated output — write it without asking. Do NOT say "no files to generate" for these operations; the JSON result IS the output artifact.
+
+---
+
+## Scope
+
+- **In scope**: Creating (`sf org create shape`), listing (`sf org list shape`), listing including inactive shapes for a specific source org (SOQL against `ShapeRepresentation`), and deleting (`sf org delete shape`) org shapes
+- **Out of scope**: Creating snapshots, creating scratch orgs (use `dx-org-manage`)
+
+---
+
+## Required Inputs
+
+Infer from the user's request:
+
+- **Operation**: create, list, list-including-inactive, or delete (see Workflow step 1)
+- **Source org** (create, delete, & list-including-inactive): Username or alias of the org to shape / whose shapes to delete or query. Passed via `--target-org`. Plain listing (Active/InProgress only) needs no source org.
+
+Notes:
+- There is **no** `--name` or `--description` flag — a shape is identified by the source org's ID, not a custom name.
+- There is **no** `--target-dev-hub` flag — the shape commands operate on the source org directly, not a Dev Hub.
+
+---
+
+## Workflow
+
+1. **Identify the operation** and match it to the command pattern below.
+2. **For create/delete, confirm the source org** — identify the username/alias. If not provided, check the default with `sf config get target-org`.
+3. **Execute via Bash tool** with the `--json` flag.
+4. **Report the result** (see Output Expectations and the example files).
+
+### Command Patterns
+
+| Operation | User intent | Execute via Bash tool |
+|-----------|-------------|------------------------|
+| **Create** | Create shape from an org | `sf org create shape --target-org <alias> --json` |
+| **Create** | Create shape from the default target org | `sf org create shape --json` |
+| **List** | List all org shapes + IDs/status (Active/InProgress only) | `sf org list shape --json` |
+| **List** | Save the list to a file | `sf org list shape --json > tmp/MyOrgShapeList.json` |
+| **List (including inactive)** | List *all* shapes — including `Inactive` ones — for a specific source org | `sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json` |
+| **Delete** | Delete shapes for an org (with confirm prompt) | `sf org delete shape --target-org <alias> --json` |
+| **Delete** | Delete shapes without prompting (scripts/CI) | `sf org delete shape --target-org <alias> --no-prompt --json` |
+
+After creating a shape, run `sf org list shape --json` to get its **org ID**.
+
+### Listing Inactive Shapes
+
+`sf org list shape` has **no flag** to surface `Inactive` shapes and **no `--target-org`** flag (it always scans every locally authenticated org). To see a source org's full shape history — including shapes superseded by a later `sf org create shape` run — query `ShapeRepresentation` directly:
+
+```bash
+sf data query --target-org <alias> --query "SELECT Id, Name, Status, CreatedDate, LastModifiedDate FROM ShapeRepresentation" --json
+```
+
+Only use this query when the user explicitly asks for **inactive** or **all/historical** shapes for a named source org. For ordinary "list my org shapes" requests, keep using `sf org list shape` — it is the documented, cross-org command and matches the rest of this skill's behavior.
+
+Notes:
+- `ShapeRepresentation` has no `SourceOrgId`, `username`, or `alias` field — report the raw query fields (`Id`, `Name`, `Status`, `CreatedDate`, `LastModifiedDate`) as returned; do not invent an `orgId`/`username`/`alias` for these rows.
+- Add `WHERE Status = 'Inactive'` to scope to only inactive shapes if the user asks for inactive shapes specifically (as opposed to "all"/"history").
+- Requires the same `ShapeRepresentation` CRUD access as create/delete.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Always use `--json` flag | Provides structured output for reliable parsing and error handling |
+| Source org must have **Org Shape for Scratch Orgs** enabled | Without it, create/delete fail with a no-access error — enable via **Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs** in the source org |
+| User needs access to the `ShapeRepresentation` object | Without CRUD access, create fails with `NoCrudAccessCreateShape` — ask the org admin |
+| `--target-org` is the SOURCE org, not a Dev Hub | Create/delete operate *on* this org; it is not a Dev Hub operation. List takes no `--target-org` |
+| No `--name` / `--description` flags | A shape is keyed off the source org's ID, not a custom name |
+| One active shape per source org | Re-running create replaces the prior shape (marks it inactive). `delete` removes **all** shapes for the org |
+| `delete` prompts for confirmation by default | Use `--no-prompt` (`-p`) for non-interactive/CI use; declining the prompt aborts with no deletion |
+
+---
+
+## Troubleshooting
+
+| Issue | Resolution |
+|-------|------------|
+| `ShapeRepresentationNoAccess` — "The org needs to be enabled for org shape before one can be created" | Source org isn't enabled for org shape — in the source org go to **Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs**, turn it on, then retry |
+| `NoCrudAccessCreateShape` — "Can't create org shape. Contact the org admin..." | You lack access to the `ShapeRepresentation` object — ask the org admin to grant access, then retry |
+| `ShapeCreateFailed` — "Error creating scratch definition file..." | Generic create failure — verify the source org is reachable/authenticated and retry; if it persists, contact Salesforce support |
+| `UNKNOWN_EXCEPTION` on create (generic error with a support ErrorId, reproducible on retry) | The source org is not fully enabled for org shape even though `ShapeRepresentation` may be partially visible — confirm **Setup → Scratch Orgs → Enable Org Shape for Scratch Orgs** is on in the source org and that your user has CRUD on `ShapeRepresentation`, then retry |
+| `sf org list shape` returns an empty list | No shapes exist yet (or none are `Active`/`InProgress`) — create one with `sf org create shape` |
+| `sf org list shape` doesn't show a shape the user expects | It only surfaces `Active`/`InProgress` shapes and has no flag to change this — a prior `sf org create shape` run may have marked it `Inactive`. Use the SOQL query in "Listing Inactive Shapes" against that specific source org instead |
+| Delete exits with code 68 (partial failure) | Some shapes failed to delete — inspect the `failures` array in the JSON for per-shape messages, then retry |
+| Delete exits with code 1 (all failed) | Deletion failed entirely — confirm the org is enabled for org shape and you have access |
+| `No org found for <alias>` / `NamedOrgNotFoundError` | Source org alias doesn't exist or isn't authenticated — verify with `sf org list` or re-auth with `sf org login web` |
+| No default target org and `--target-org` omitted | Provide `--target-org <alias>` or set a default with `sf config set target-org=<alias>` |
+
+---
+
+## Output Expectations
+
+All commands return JSON when `--json` is used:
+
+- **Create** → `shapeId`, `success`, and `errors`.
+- **List** → an array of shapes, each with `orgId`, `username`, `alias`, `shapeId`, `status` (`Active` or `InProgress`), `createdBy`, and `createdDate`.
+- **List (including inactive)** → a SOQL query result (`records`, `totalSize`, `done`), each record with `Id`, `Name`, `Status` (`Active`, `InProgress`, or `Inactive`), `CreatedDate`, and `LastModifiedDate` — no `orgId`/`username`/`alias`, since `ShapeRepresentation` has no such fields.
+- **Delete** → `orgId`, `shapeIds` (deleted), and `failures`. Returns no result if the user declines the confirmation prompt.
+
+See the example files referenced below for full response structures.
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| Create a scratch org, or create/use a snapshot | `dx-org-manage` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `examples/create_success_output.json` | To understand the successful shape-creation response structure |
+| `examples/create_error_output.json` | To handle common create error scenarios |
+| `examples/list_output.json` | To understand the list response structure (org IDs, status) |
+| `examples/list_inactive_output.json` | To understand the SOQL query response structure for listing shapes including `Inactive` ones |
+| `examples/delete_output.json` | To understand the delete response structure (deleted IDs, failures) |
+| `references/cli_flags.md` | For detailed explanation of all flags across create/list/delete |

package/skills/dx-org-shape-manage/examples/create_error_output.json

@@ -0,0 +1,9 @@
+{
+  "status": 1,
+  "name": "ShapeRepresentationNoAccess",
+  "message": "The org needs to be enabled for org shape before one can be created. test-org@example.com",
+  "exitCode": 1,
+  "commandName": "OrgShapeCreateCommand",
+  "stack": "ShapeRepresentationNoAccess: The org needs to be enabled for org shape before one can be created...",
+  "warnings": []
+}

package/skills/dx-org-shape-manage/examples/create_success_output.json

@@ -0,0 +1,9 @@
+{
+  "status": 0,
+  "result": {
+    "shapeId": "3SR5g00000001ABCAA",
+    "success": true,
+    "errors": []
+  },
+  "warnings": []
+}

package/skills/dx-org-shape-manage/examples/delete_output.json

@@ -0,0 +1,11 @@
+{
+  "status": 0,
+  "result": {
+    "orgId": "00D5g00000001XyEAI",
+    "shapeIds": [
+      "3SR5g00000001ABCAA"
+    ],
+    "failures": []
+  },
+  "warnings": []
+}