@salesforce/afv-skills 1.34.0 → 1.35.0

package/skills/dx-apexguru-scan/scripts/run-scan.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Submit a zip to the ApexGuru SFAP Scan API and poll to completion.
+#
+# Usage:
+#   bash run-scan.sh <zip-path> <raw-result-out.json> [--org <alias>] [--fast]
+#                    [--max-polls N] [--interval SEC]
+#   The endpoint (prod/stage/dev host) is chosen by resolve-token.sh from the
+#   token's environment; customers on a prod org always hit api.salesforce.com.
+#
+# Steps:
+#   1. resolve-token.sh → baseUrl + JWT
+#   2. POST {baseUrl}/scan  (multipart file upload) → 202 {scanId, status}
+#   3. GET  {baseUrl}/scan/{scanId} every ~15s until SUCCEEDED/FAILED
+#   4. Write the final raw SUCCEEDED body verbatim to <raw-result-out.json>
+#      (report stays base64-encoded here; decode-report.js handles it).
+#
+# Progress lines go to STDERR so stdout stays a single clean JSON summary:
+#   {"scanId":"...","status":"SUCCEEDED","analysisMode":"static|full",
+#    "violationCount":N,"filesScanned":N,"rawResult":"<path>"}
+# On failure: {"error":"...","status":"...","httpStatus":NNN,"hint":"..."} exit 1.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+ZIP_PATH="${1:-}"
+RAW_OUT="${2:-}"
+shift 2 2>/dev/null || true
+
+FAST=""
+ORG_ALIAS=""
+MAX_POLLS=40          # 40 * 15s = 10 min ceiling
+INTERVAL=15
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --org) ORG_ALIAS="${2:-}"; shift 2 ;;
+    --fast) FAST="true"; shift ;;
+    --max-polls) MAX_POLLS="${2:-40}"; shift 2 ;;
+    --interval) INTERVAL="${2:-15}"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+err() { # msg httpStatus status hint
+  jq -cn --arg m "$1" --argjson h "${2:-0}" --arg s "${3:-}" --arg hint "${4:-}" \
+    '{error:$m, httpStatus:$h, status:$s, hint:$hint}'
+  exit 1
+}
+
+[ -n "$ZIP_PATH" ] && [ -f "$ZIP_PATH" ] || err "zip not found: $ZIP_PATH" 0 "" "run build-zip.sh first"
+[ -n "$RAW_OUT" ] || err "missing raw output path" 0 "" "usage: run-scan.sh <zip> <raw-out.json>"
+
+# --- 1. token ---
+RESOLVE_ARGS=()
+[ -n "$ORG_ALIAS" ] && RESOLVE_ARGS+=(--org "$ORG_ALIAS")
+CREDS="$(bash "$SCRIPT_DIR/resolve-token.sh" ${RESOLVE_ARGS[@]+"${RESOLVE_ARGS[@]}"})" || {
+  echo "$CREDS" >&2; exit 1;
+}
+BASE_URL="$(echo "$CREDS" | jq -r '.baseUrl')"
+# The JWT is a secret: resolve-token.sh returns a 0600 file PATH, never the token
+# itself. Read it into memory and delete the file right away so it never lingers.
+TOKEN_FILE="$(echo "$CREDS" | jq -r '.tokenFile')"
+TOKEN=""
+if [ -n "$TOKEN_FILE" ] && [ -f "$TOKEN_FILE" ]; then
+  TOKEN="$(cat "$TOKEN_FILE")"
+  rm -f "$TOKEN_FILE"
+fi
+[ -n "$TOKEN" ] || err "could not read resolved token" 0 "" "re-run; if it persists, resolve the token manually via APEXGURU_SFAP_TOKEN"
+
+hint_for_status() { # maps HTTP status → actionable hint (see references/error-handling.md)
+  case "$1" in
+    401) echo "Token bad or expired. Re-authenticate the Salesforce org (or supply a fresh sfap_api JWT) and retry." ;;
+    403) echo "Scan owned by a different org. The token's tnk-claim org must match the scan owner." ;;
+    404) echo "Unknown scanId, or the scan was archived (~30-day GC). Re-submit." ;;
+    400) echo "Malformed zip, no Apex inside, or over size limit (200MB compressed / 1GB decompressed)." ;;
+    *)   echo "See references/error-handling.md." ;;
+  esac
+}
+
+# Auto-enable fast mode if >10 Apex files (unless explicitly disabled)
+if [ -z "$FAST" ]; then
+  # grep -c exits non-zero when there are no matches; capture the count without
+  # letting that non-zero status trip `set -e`, and default an empty result to 0.
+  FILE_COUNT=$(unzip -l "$ZIP_PATH" 2>/dev/null | grep -c '\.cls$' || true)
+  FILE_COUNT=${FILE_COUNT:-0}
+  if [ "$FILE_COUNT" -gt 10 ]; then
+    FAST="true"
+    echo "Auto-enabling fast mode (detected $FILE_COUNT Apex files)" >&2
+  fi
+fi
+
+# --- 2. submit ---
+echo "Submitting scan to $BASE_URL/scan ..." >&2
+SUBMIT_BODY="$(mktemp)"
+FAST_ARG=()
+[ -n "$FAST" ] && FAST_ARG=(-F "fastMode=true")
+
+HTTP=$(curl -sS -o "$SUBMIT_BODY" -w '%{http_code}' -X POST "$BASE_URL/scan" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "x-apexguru-client: ApexGuru-Skill" \
+  -F "file=@${ZIP_PATH};type=application/zip" \
+  ${FAST_ARG[@]+"${FAST_ARG[@]}"}) || err "network error submitting scan" 0 "" "check connectivity to the API host"
+
+if [ "$HTTP" != "202" ] && [ "$HTTP" != "200" ]; then
+  MSG="$(jq -r '.message // .error // empty' "$SUBMIT_BODY" 2>/dev/null || true)"
+  rm -f "$SUBMIT_BODY"
+  err "submit failed: ${MSG:-HTTP $HTTP}" "$HTTP" "" "$(hint_for_status "$HTTP")"
+fi
+
+SCAN_ID="$(jq -r '.scanId // empty' "$SUBMIT_BODY")"
+rm -f "$SUBMIT_BODY"
+[ -n "$SCAN_ID" ] || err "no scanId in submit response" "$HTTP" "" "unexpected API response shape"
+echo "Accepted. scanId=$SCAN_ID (polling every ${INTERVAL}s, up to $MAX_POLLS times)..." >&2
+
+# --- 3. poll ---
+POLL_BODY="$(mktemp)"
+STATUS="QUEUED"
+i=0
+while [ "$i" -lt "$MAX_POLLS" ]; do
+  i=$((i + 1))
+  sleep "$INTERVAL"
+  HTTP=$(curl -sS -o "$POLL_BODY" -w '%{http_code}' -X GET "$BASE_URL/scan/$SCAN_ID" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "x-apexguru-client: ApexGuru-Skill") || { echo "poll $i: network hiccup, retrying" >&2; continue; }
+
+  if [ "$HTTP" != "200" ]; then
+    MSG="$(jq -r '.message // .error // empty' "$POLL_BODY" 2>/dev/null || true)"
+    rm -f "$POLL_BODY"
+    err "poll failed: ${MSG:-HTTP $HTTP}" "$HTTP" "$STATUS" "$(hint_for_status "$HTTP")"
+  fi
+
+  STATUS="$(jq -r '.status // "UNKNOWN"' "$POLL_BODY")"
+  echo "poll $i/$MAX_POLLS: $STATUS" >&2
+
+  case "$STATUS" in
+    SUCCEEDED)
+      cp "$POLL_BODY" "$RAW_OUT"
+      rm -f "$POLL_BODY"
+      jq -c '{status, violationCount, filesScanned, rawResult: "'"$RAW_OUT"'"}' "$RAW_OUT"
+      exit 0
+      ;;
+    FAILED)
+      MSG="$(jq -r '.message // "scan reported FAILED"' "$POLL_BODY")"
+      rm -f "$POLL_BODY"
+      err "$MSG" "$HTTP" "FAILED" "Inspect the message; re-submit after addressing it."
+      ;;
+    QUEUED|RUNNING) : ;; # keep polling
+    *) echo "poll $i: unexpected status '$STATUS', continuing" >&2 ;;
+  esac
+done
+
+rm -f "$POLL_BODY"
+err "scan did not finish within $((MAX_POLLS * INTERVAL))s (last status: $STATUS)" 0 "$STATUS" \
+  "Large projects can take longer — re-run with --max-polls higher, or use --fast."

package/skills/dx-apexguru-scan/scripts/scan.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# One-shot ApexGuru performance scan: package → submit+poll → decode+present.
+#
+# This wrapper runs all three steps of the workflow in a single command so the
+# scan cannot be left half-finished (a bare run-scan.sh already prints a
+# violation count, which can read as "done" and tempt an early stop before the
+# report is decoded). The FINAL stdout of this script is the ready-to-present
+# markdown report from decode-report.js --present — print that to the user
+# verbatim.
+#
+# Usage:
+#   bash scan.sh <project-root> [--out <report.md>]
+#                [--org <alias>] [--fast] [--raw <raw-out.json>]
+#
+#   <project-root>  folder that contains Apex somewhere beneath it (defaults to
+#                   CWD if omitted or given as "."). build-zip.sh collects every
+#                   .cls/.trigger under it, any layout.
+#   --out FILE      also write the presented markdown to FILE (e.g. report.md).
+#   --org ALIAS     forwarded to run-scan.sh (which sf org to derive the JWT from).
+#   --fast          forwarded to run-scan.sh (skip LLM-heavy fix generation).
+#   --raw FILE      keep the raw SUCCEEDED JSON at FILE (default: a temp file).
+#
+# The endpoint (prod/stage/dev) is chosen from the token's env by resolve-token.sh;
+# customers on a prod org always hit api.salesforce.com.
+#
+# Progress for each step streams to STDERR; only the final presented markdown
+# goes to STDOUT. On any step failure, the failing step's JSON error/hint is
+# surfaced to stderr and the script exits non-zero.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+PROJECT_ROOT=""
+OUT_FILE=""
+RAW_OUT=""
+ORG_ALIAS=""
+FAST=""
+
+# First non-flag arg is the project root.
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --out) OUT_FILE="${2:-}"; shift 2 ;;
+    --raw) RAW_OUT="${2:-}"; shift 2 ;;
+    --org) ORG_ALIAS="${2:-}"; shift 2 ;;
+    --fast) FAST="--fast"; shift ;;
+    *) [ -z "$PROJECT_ROOT" ] && PROJECT_ROOT="$1"; shift ;;
+  esac
+done
+
+[ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$(pwd)"
+[ "$PROJECT_ROOT" = "." ] && PROJECT_ROOT="$(pwd)"
+
+TS="$(date +%Y%m%d-%H%M%S)"
+WORK_DIR="$(mktemp -d)"
+ZIP_PATH="$WORK_DIR/apexguru-${TS}.zip"
+[ -n "$RAW_OUT" ] || RAW_OUT="$WORK_DIR/apexguru-raw-${TS}.json"
+
+cleanup() { [ -n "${WORK_DIR:-}" ] && rm -rf "$WORK_DIR" 2>/dev/null || true; }
+trap cleanup EXIT
+
+# --- Step 1: package the project's Apex into a zip ---
+echo "[scan] Step 1/3: packaging $PROJECT_ROOT ..." >&2
+ZIP_JSON="$(bash "$SCRIPT_DIR/build-zip.sh" "$PROJECT_ROOT" "$ZIP_PATH")" || {
+  echo "$ZIP_JSON" >&2
+  echo "[scan] packaging failed — see the error/hint above." >&2
+  exit 1
+}
+echo "[scan] packaged: $(echo "$ZIP_JSON" | jq -r '.humanSize // "?"') → $(echo "$ZIP_JSON" | jq -r '.zip')" >&2
+
+# --- Step 2: submit + poll to completion ---
+echo "[scan] Step 2/3: submitting and polling the scan ..." >&2
+RUN_ARGS=("$ZIP_PATH" "$RAW_OUT")
+[ -n "$ORG_ALIAS" ] && RUN_ARGS+=(--org "$ORG_ALIAS")
+[ -n "$FAST" ] && RUN_ARGS+=("$FAST")
+RUN_JSON="$(bash "$SCRIPT_DIR/run-scan.sh" "${RUN_ARGS[@]}")" || {
+  echo "$RUN_JSON" >&2
+  echo "[scan] scan failed — see the error/hint above." >&2
+  exit 1
+}
+echo "[scan] scan complete: $(echo "$RUN_JSON" | jq -r '.violationCount // "?"') violations" >&2
+
+# --- Step 3: decode + present (this is the deliverable) ---
+echo "[scan] Step 3/3: decoding and presenting the report ..." >&2
+PRESENTED="$(node "$SCRIPT_DIR/decode-report.js" "$RAW_OUT" --present)" || {
+  echo "[scan] decoding failed against $RAW_OUT" >&2
+  exit 1
+}
+
+# Optionally persist the presented markdown (e.g. so it survives temp cleanup).
+if [ -n "$OUT_FILE" ]; then
+  printf '%s\n' "$PRESENTED" > "$OUT_FILE"
+  echo "[scan] report also written to $OUT_FILE" >&2
+fi
+
+# FINAL stdout: the ready-to-present markdown. Print this to the user verbatim.
+printf '%s\n' "$PRESENTED"

package/skills/dx-apexguru-scan/scripts/validate-token.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Locally sanity-check an SFAP JWT *before* any network call, so a bad token
+// fails fast with a clear reason instead of a bare HTTP 401 deep in the poll
+// loop. This does NOT verify the signature (only the server can) — it decodes
+// the freely-readable header/body claims to catch the two things that cause
+// almost every 401: missing sfap_api scope, or expired.
+//
+// The token's environment (prod/stage/dev) is detected from its tnk claim and
+// reported as detectedEnv so the caller can route to the matching endpoint.
+//
+// The token is read from STDIN (never argv) so it does not leak into the
+// process list. Usage:
+//   printf '%s' "$JWT" | node validate-token.js [--now <epoch>]
+//
+// Output (stdout, single-line JSON):
+//   pass:  {"ok":true,"tnk":"...","detectedEnv":"prod|stage|dev|null","expiresInSeconds":N,"warnings":[...]}
+//   fail:  {"ok":false,"error":"...","hint":"..."}  (exit 1)
+// A "fail" only happens for things we can PROVE wrong (expired / missing scope).
+// Anything we cannot read is a warning, not a block.
+
+function out(obj, code) {
+  console.log(JSON.stringify(obj));
+  process.exit(code);
+}
+
+const args = process.argv.slice(2);
+let now = Math.floor(Date.now() / 1000);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--now") now = parseInt(args[++i], 10) || now;
+}
+
+// Read the token from stdin (keeps it out of argv / process list).
+let token = "";
+try {
+  token = require("fs").readFileSync(0, "utf8").trim();
+} catch {
+  token = "";
+}
+if (!token) out({ ok: false, error: "no token on stdin", hint: "resolve the token before validating" }, 1);
+
+// A JWT is header.body.signature, each a base64url-encoded chunk.
+function decodeSegment(seg) {
+  const b64 = seg.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+  return JSON.parse(Buffer.from(pad, "base64").toString("utf8"));
+}
+
+const parts = token.split(".");
+if (parts.length < 2) {
+  // Not a JWT we can read — don't block (token may be an opaque format).
+  out({ ok: true, tnk: null, detectedEnv: null, expiresInSeconds: null, warnings: ["token is not a readable JWT — skipping local checks"] }, 0);
+}
+
+let header, body;
+try {
+  header = decodeSegment(parts[0]);
+  body = decodeSegment(parts[1]);
+} catch {
+  out({ ok: true, tnk: null, detectedEnv: null, expiresInSeconds: null, warnings: ["could not decode JWT claims — skipping local checks"] }, 0);
+}
+
+const warnings = [];
+
+// --- 1. tnk / environment. Per the SFAP contract, tnk lives on the HEADER and
+// looks like core/<instance>/<orgId> (e.g. core/prod/00D..., core/stagecomstg2/...,
+// core/falcondeva/...). The environment marker lives ONLY in the <instance>
+// segment — the trailing <orgId> (00D...) is an opaque id that must NOT be
+// scanned for substrings, or a prod org whose id happens to contain "dev"/"stg"
+// would be wrongly rejected. So we match markers against the instance segment
+// and the iss host only, never the whole claim string. The detected env is
+// reported (not rejected) so the caller can route to the matching endpoint. ---
+const tnk = header.tnk || body.tnk || null;
+const iss = body.iss || "";
+// tnk instance segment = the middle of core/<instance>/<orgId>; fall back to the
+// whole tnk only if it isn't in that 3-part shape.
+const tnkParts = tnk ? String(tnk).split("/") : [];
+const tnkInstance = tnkParts.length >= 3 ? tnkParts[1] : tnk || "";
+// iss host (strip scheme/path) so we match the host label, not a full URL.
+const issHost = String(iss).replace(/^https?:\/\//, "").split(/[/?#]/)[0];
+const envHay = `${tnkInstance} ${issHost}`.toLowerCase();
+const looksDev = /falcondeva|falcondev|falcontest|deva|(^|[^a-z])dev([^a-z]|$)/.test(envHay);
+const looksStage = /stg|stage/.test(envHay);
+// Env inferred from the token's own claims (null when we can't tell). Production
+// instances carry no stg/dev marker, so a readable tnk with neither signal is prod.
+const detectedEnv = looksStage && !looksDev
+  ? "stage"
+  : looksDev && !looksStage
+  ? "dev"
+  : tnk && !looksStage && !looksDev
+  ? "prod"
+  : null;
+
+if (!tnk) warnings.push("no tnk claim found — could not detect the token's environment; defaulting to prod endpoint");
+
+// --- 2. scope must include sfap_api. Scope may be a space-delimited string
+// (scp/scope) or an array. Only fail if we can read it AND sfap_api is absent. ---
+const scopeRaw = body.scp ?? body.scope ?? null;
+if (scopeRaw != null) {
+  const scopes = Array.isArray(scopeRaw) ? scopeRaw : String(scopeRaw).split(/\s+/);
+  if (!scopes.includes("sfap_api")) {
+    out({ ok: false, error: "token scope does not include sfap_api",
+          hint: "Re-mint the token with the sfap_api scope. See references/authentication.md." }, 1);
+  }
+} else {
+  warnings.push("no scope claim found — could not confirm sfap_api scope");
+}
+
+// --- 3. expiry. exp is epoch seconds. Fail if already past. ---
+let expiresInSeconds = null;
+if (typeof body.exp === "number") {
+  expiresInSeconds = body.exp - now;
+  if (expiresInSeconds <= 0) {
+    out({ ok: false, error: `token expired ${Math.abs(expiresInSeconds)}s ago`,
+          hint: "Re-mint a fresh SFAP token and retry." }, 1);
+  }
+  if (expiresInSeconds < 60) warnings.push(`token expires in ${expiresInSeconds}s — it may lapse mid-scan`);
+} else {
+  warnings.push("no exp claim found — could not confirm the token is unexpired");
+}
+
+out({ ok: true, tnk, detectedEnv, expiresInSeconds, warnings }, 0);

package/skills/dx-devops-pipeline-manage/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: dx-devops-pipeline-manage
+description: "Use this skill to manage the full lifecycle of a DevOps Center pipeline — list all pipelines, get a single pipeline's details, create a new pipeline linked to a Git repository, add or remove stages, rename a stage, add or remove Salesforce environments on stages, attach or detach projects, and activate or deactivate the pipeline. Invoke when the user wants to set up a release pipeline, wire promotion stages across integration, UAT, staging, and production orgs, connect environments to stages, attach a project, or activate a continuous delivery pipeline. Uses sf devops pipeline and sf devops stage commands with --json output. DO NOT TRIGGER for work-item lifecycle, promotion or deployment execution, conflict detection, or standalone project creation (separate skills)."
+metadata:
+  version: "1.0"
+  minApiVersion: "58.0"
+  relatedSkills:
+    - "dx-devops-work-item-manage"
+  accessCheck:
+    - type: "orgPref"
+      value: "ALMDevopsCorePref"
+    - type: "userPerm"
+      value: "UserHasDevOpsCore"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# DevOps Center Pipeline Management
+
+Manages the complete pipeline lifecycle in DevOps Center — from creation against a repository, through stage and environment configuration and project attachment, to activation of a ready-to-promote release pipeline. Provides headless CLI-driven operations for autonomous release workflows.
+
+## Scope
+
+- **In scope**: List pipelines, get pipeline details, create a pipeline (linked to an existing or new Git repo), add/delete/rename stages, add/delete Salesforce environments on stages, attach/detach projects, and activate/deactivate/rename the pipeline
+- **Out of scope**: Work-item lifecycle, promotion/deployment execution, conflict detection, standalone project creation (separate skills)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Operation type**: list, get, create, add-stage, delete-stage, rename-stage, add-environment, delete-environment, attach-project, detach-project, activate, or deactivate
+- **For get / any stage or environment op**: pipeline ID (required) — obtain via `sf devops pipeline list --json`
+- **For create**: pipeline name (required) and a Git repo (`--repo`, required). Repo flags differ by scenario:
+  - **Existing repo (GitHub or Bitbucket)**: only `--repo <url>` — do **not** pass `--repo-type`/`--create-repo`
+  - **New GitHub repo**: `--repo <name> --create-repo --repo-type github --repo-owner <org-or-user>`
+  - **New Bitbucket repo**: `--repo <name> --create-repo --repo-type bitbucket --bitbucket-workspace <workspace>` (`--bitbucket-project-key <key>` optional)
+  - Description (`--description`) optional in all cases
+- **For add-stage**: pipeline ID, new stage name, and `--next-stage-id` (the stage the new one precedes) — get stage IDs via `sf devops pipeline get`
+- **For add-environment**: pipeline ID, stage ID, environment name, and `--org-type` (Production or Sandbox)
+- **For attach/detach-project**: pipeline ID and project ID
+- **For activate/deactivate/rename**: pipeline ID
+
+Defaults unless specified:
+- Output format: `--json` for headless consumption
+- Target org: use `--target-org <alias>` if not relying on the default org
+
+If the user gives a clear request ("create a pipeline on repo myorg/myrepo", "add a UAT stage before Production", "activate pipeline 0XB..."), proceed immediately without unnecessary questions.
+
+---
+
+## Workflow
+
+All operations use `sf devops pipeline` and `sf devops stage` CLI commands with `--json` output for structured consumption. Pipeline IDs and stage IDs are the primary identifiers — resolve them via `list` and `get` before mutating.
+
+### Phase 1 — Identify Operation
+
+1. **Determine the operation type** from user intent:
+   - "list", "show all pipelines" → list; "details of pipeline", "show stages" → get
+   - "create", "set up", "new pipeline" → create
+   - "add stage", "insert stage" → add-stage; "rename stage" → rename-stage; "remove/delete stage" → delete-stage
+   - "connect environment", "add org to stage" → add-environment; "remove environment" → delete-environment
+   - "attach project", "connect project" → attach-project; "detach project" → detach-project
+   - "activate", "turn on"; "deactivate", "turn off"; "rename pipeline" → lifecycle update
+
+### Phase 2 — Execute Operation
+
+2. **Verify org authentication** before any operation:
+   ```bash
+   sf org display --json
+   ```
+   - If no default org is set or auth has expired, instruct the user to run `sf org login web --set-default --alias <alias>`
+   - Confirm the org has DevOps Center enabled by running `sf devops pipeline list --json`
+   - Add `--target-org <alias>` to every command when targeting a specific org
+
+3. **Inspect pipelines**:
+   ```bash
+   sf devops pipeline list --json                              # all pipelines in the org
+   sf devops pipeline get --pipeline-id <pipeline-id> --json   # one pipeline, with stages/repos/projects
+   ```
+   - `list` returns SObject records under `.result.pipelines[]` with capitalized fields (`.Id`, `.Name`, `.IsActive`) — it does **not** include stages or connected projects
+   - `get` returns a single pipeline under `.result` with camelCase fields (`.id`, `.name`, `.stages[]`, `.connectedProjects[]`); each stage has `.id`, `.name`, `.nextStageId`, `.branchName`, and `.environment.{id,name}`. **Stages are a linked list** — order is defined by `nextStageId`, and the terminal stage has `nextStageId: null`. Use `get` to discover **stage IDs** before any stage or environment operation
+
+4. **Create a pipeline** — the pipeline must be linked to a Git repository. `--name` and `--repo` are always required; the remaining flags depend on the repo scenario:
+   ```bash
+   # Existing repo (GitHub or Bitbucket) — pass the full repo URL, nothing else
+   sf devops pipeline create --name "<pipeline-name>" --repo <repo-url> --json
+
+   # New GitHub repo — requires --repo-owner
+   sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
+     --create-repo --repo-type github --repo-owner <org-or-user> --json
+
+   # New Bitbucket repo — requires --bitbucket-workspace (--bitbucket-project-key optional)
+   sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
+     --create-repo --repo-type bitbucket --bitbucket-workspace <workspace> \
+     --bitbucket-project-key <key> --json
+
+   # Custom stage chain (any scenario) — repeat --stage in promotion order
+   sf devops pipeline create --name "<pipeline-name>" --repo <repo-url> \
+     --stage Dev --stage QA --stage Prod --json
+   ```
+   - Provider-specific required flags: **GitHub new repo** → `--repo-owner`; **Bitbucket new repo** → `--bitbucket-workspace`. Omitting the provider's required flag fails the create
+   - Do **not** pass `--repo-type`/`--create-repo` for an existing repo — supply only the repo URL via `--repo`
+   - **Custom stages at create time**: a new pipeline seeds the default stage chain **Integration → UAT → Staging → Production**. To seed different stages, repeat `-s/--stage` once per stage **in promotion order** — e.g. `--stage Dev --stage QA --stage Prod`. This avoids adding/renaming stages afterward
+   - Add `--description "<text>"` optionally in any scenario
+   - Capture the returned pipeline ID for subsequent stage/environment/project/activation steps
+   - **Idempotency**: the CLI does not dedupe. Before creating, run `sf devops pipeline list --json` and check for a pipeline with the same name/repo; return the existing one if found. See `references/parsing-patterns.md` for the check-before-create snippet
+
+5. **Configure stages** — a stage is added relative to an existing stage, then bound to an environment. **Read `references/cli-commands.md`** for full flag details before multi-stage work:
+   ```bash
+   # Insert an empty stage BEFORE an existing stage (get the next-stage-id from `pipeline get`)
+   sf devops pipeline stage add --pipeline-id <id> --name "<stage-name>" --next-stage-id <stage-id> --json
+   # Rename a stage
+   sf devops pipeline stage update --pipeline-id <id> --stage-id <stage-id> --name "<new-name>" --json
+   # Delete a stage (predecessor auto-relinks to successor)
+   sf devops pipeline stage delete --pipeline-id <id> --stage-id <stage-id> --json
+   ```
+   - `stage add` inserts an **empty** stage (no branch/environment) before `--next-stage-id`; configure its environment separately
+   - Build the promotion chain by inserting each new stage before the stage that should follow it
+
+6. **Bind environments to stages** — attach a Salesforce org to a stage:
+   ```bash
+   # Validate the org-type against the fixed enum BEFORE calling the CLI
+   bash scripts/validate-org-type.sh "<Production|Sandbox>"   # exits non-zero on an invalid value
+   sf devops stage environment add --pipeline-id <id> --stage-id <stage-id> \
+     --environment-name "<env-name>" --org-type <Production|Sandbox> --json
+   # Remove an environment (pipeline must be inactive)
+   sf devops stage environment delete --pipeline-id <id> --environment-id <env-id> --json
+   ```
+   - `--org-type` must be exactly `Production` or `Sandbox` — run `scripts/validate-org-type.sh <value>` first and only proceed on exit 0
+   - **Headless caveat**: `stage environment add` triggers an OAuth browser flow. In headless/CI runs pass `--no-browser` — the CLI prints a redirect URL for manual authentication
+
+7. **Attach / detach a project** — a project can be attached to only one pipeline:
+   ```bash
+   sf devops pipeline project add --pipeline-id <id> --project-id <project-id> --json
+   sf devops pipeline project delete --pipeline-id <id> --project-id <project-id> --json
+   ```
+   - If the user names a project instead of providing its ID, resolve it via `sf devops project list --json` (see `references/parsing-patterns.md`)
+
+8. **Activate / deactivate / rename the pipeline**:
+   ```bash
+   # Before activating, confirm the deterministic ≥1-stage prerequisite
+   bash scripts/check-activation-ready.sh <id> [target-org]   # exits non-zero if stage-less
+   sf devops pipeline update --pipeline-id <id> --activate --json             # activate
+   sf devops pipeline update --pipeline-id <id> --deactivate --json           # deactivate
+   sf devops pipeline update --pipeline-id <id> --name "<new-name>" --json    # rename
+   ```
+   - Before `--activate`, run `scripts/check-activation-ready.sh <id>` and only proceed on exit 0 — it fails with an actionable message when the pipeline has no stages
+   - **Stages cannot be modified after the pipeline is activated and changes are promoted through it** — finish stage/environment configuration before activating
+   - `--activate` and `--deactivate` are mutually exclusive; `--deactivate` and `--name` may be combined in one command
+
+### Phase 3 — Verify and Report
+
+9. **Verify operation success** — use `scripts/verify-operation.sh`, which performs the deterministic JSON-status and post-state field checks and exits non-zero with an actionable message on mismatch:
+   ```bash
+   # Assert a captured command's JSON status is 0 (pipe the CLI output in)
+   sf devops pipeline update --pipeline-id <id> --activate --json | bash scripts/verify-operation.sh status -
+   # Assert post-state after activate / stage / project ops
+   bash scripts/verify-operation.sh active      <id> true         [target-org]   # isActive == true
+   bash scripts/verify-operation.sh has-stage   <id> "<stage>"    [target-org]   # stage present in chain
+   bash scripts/verify-operation.sh has-project <id> "<project>"  [target-org]   # project connected
+   ```
+   - **Create**: confirm the pipeline appears in `sf devops pipeline list --json` by `.Name` and capture its `.Id`
+   - **Stage / environment / project changes**: verify with the `has-stage` / `has-project` modes above (they read `sf devops pipeline get` and check `.result.stages[]` / `.result.connectedProjects[]`)
+   - **Activate**: verify with the `active <id> true` mode
+
+10. **Report results**:
+    - **List**: pipeline name, ID, and active state per pipeline (no stages — that's what `get` is for)
+    - **Get**: pipeline name, ID, active state, stage chain (each stage's name → environment → branch, ordered via `nextStageId`), connected projects
+    - **Create**: pipeline ID, name, and linked repo (or "existing pipeline returned" on idempotent match)
+    - **Stage / environment / project op**: the resulting stage chain with each stage's environment, in promotion order
+    - **Lifecycle**: the new active state and/or name
+
+### Verification Checklist (gate before reporting success)
+
+Confirm the items for the operation you performed. Do **not** report success until every applicable box holds:
+
+- [ ] Every `sf devops` command was run with `--json` and returned `status: 0` (`scripts/verify-operation.sh status -`)
+- [ ] **Create**: the new pipeline appears in `sf devops pipeline list --json` by name, and (for a new repo) the provider-specific flags were supplied (`--repo-owner` for GitHub, `--bitbucket-workspace` for Bitbucket)
+- [ ] **Add-stage / add-environment**: the stage exists in the chain and `--org-type` passed `scripts/validate-org-type.sh` (`scripts/verify-operation.sh has-stage ...`)
+- [ ] **Attach-project**: the project shows in `.result.connectedProjects[]` (`scripts/verify-operation.sh has-project ...`)
+- [ ] **Activate**: `scripts/check-activation-ready.sh` passed beforehand and `.result.isActive` is now `true` (`scripts/verify-operation.sh active <id> true`)
+- [ ] **Delete-environment**: the pipeline was inactive before the delete
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| All sf devops commands must use `--json` flag | Structured output is required for headless consumption; human-readable output is unreliable for parsing |
+| A pipeline requires a Git repo at create time | `sf devops pipeline create` requires `--name` and `--repo`; for an existing repo pass only the URL, for a new repo add `--create-repo` and `--repo-type` |
+| New-repo create needs provider-specific flags | GitHub requires `--repo-owner`; Bitbucket requires `--bitbucket-workspace` (`--bitbucket-project-key` optional). The wrong provider's flags fail the command |
+| Pipeline ID required for get, update, and all stage/environment/project ops | These commands identify the pipeline only by `--pipeline-id`; obtain it via `sf devops pipeline list` |
+| Stage IDs come from `pipeline get` | `stage add` (`--next-stage-id`), `stage update`/`delete` (`--stage-id`), and `stage environment add` (`--stage-id`) all need stage IDs |
+| `stage add` inserts an empty stage before `--next-stage-id` | Stages carry no environment until one is added; build the chain by anchoring to the following stage |
+| `--org-type` must be exactly `Production` or `Sandbox` | The flag is a fixed enum; other values fail |
+| Pipeline must have ≥1 stage before activation | `sf devops pipeline update --activate` rejects a stage-less pipeline |
+| Do not modify stages after activate + promote | DevOps Center locks stage structure once changes have been promoted through an active pipeline |
+| Environment delete requires an inactive pipeline | `stage environment delete` only succeeds while the pipeline is inactive |
+| A project attaches to only one pipeline | `pipeline project add` fails if the project is already attached elsewhere; detach first |
+| Idempotent create via check-before-create | The CLI does not dedupe; list existing pipelines and return the match instead of erroring |
+| Prefer `--no-browser` in headless runs | `stage environment add` opens an OAuth browser flow; `--no-browser` prints a redirect URL for CI |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| **No default org set** | Run `sf org display --json` first; if it fails, instruct user to run `sf org login web --set-default` |
+| **Create fails — missing repo** | `--repo` is required; pass an existing repo URL, or `--create-repo` + `--repo-type` for a new repo |
+| **New-repo create fails — missing provider flag** | GitHub new repo needs `--repo-owner`; Bitbucket new repo needs `--bitbucket-workspace`. Don't mix providers' flags (`--repo-owner` with `bitbucket`, or `--bitbucket-workspace` with `github`) |
+| **`stage add` fails — no next-stage-id** | `--next-stage-id` is required; run `sf devops pipeline get --pipeline-id <id> --json` to find the stage IDs and pick the one the new stage should precede |
+| **Environment add hangs in CI** | The OAuth browser flow blocks headless runs; add `--no-browser` and complete auth via the printed redirect URL |
+| **Activation rejected** | The pipeline needs at least one stage; add a stage (and its environment) before `--activate` |
+| **Cannot modify stages** | The pipeline is active and has promoted changes; stage structure is locked — configuration must complete before activation |
+| **Environment delete fails** | The pipeline is active; deactivate with `pipeline update --deactivate` before deleting the environment |
+| **Project already attached** | A project attaches to only one pipeline; detach from the other pipeline first via `pipeline project delete` |
+| **Pipeline / stage / project not found** | The ID is invalid; run `sf devops pipeline list --json`, `sf devops pipeline get --json`, or `sf devops project list --json` to find valid IDs |
+
+---
+
+## Output Expectations
+
+Deliverables vary by operation:
+
+- **List**: pipelines with ID, name, and active state (no stages/projects in the list view)
+- **Get**: a pipeline with ID, name, active state, its stage chain (each with environment and branch, ordered via `nextStageId`), and connected projects
+- **Create**: pipeline ID, name, and linked repository (or the pre-existing pipeline on idempotent match)
+- **Stage op**: the updated ordered stage chain
+- **Environment op**: the stage with its bound environment (name, org-type)
+- **Project op**: confirmation of attach/detach
+- **Lifecycle**: the new active state and/or pipeline name
+
+Outputs are derived from `sf devops pipeline` and `sf devops stage` CLI commands.
+
+---
+
+## Cross-Skill Integration
+
+| Delegate to | When |
+|-------------|------|
+| `dx-devops-work-item-manage` | The user wants to create or advance work items once the pipeline is active |
+
+If a project the user wants to attach can't be found, resolve or list existing projects with `sf devops project list --json` (see `references/parsing-patterns.md`) rather than delegating — project creation is out of scope for this skill.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/cli-commands.md` | When you need detailed CLI flag documentation and JSON output schemas for each `sf devops pipeline` / `sf devops stage` command |
+| `references/parsing-patterns.md` | When you need jq snippets to parse the JSON (stage chains, pipeline/project ID resolution), error-handling reference, the check-before-create idempotent pattern, or auth requirements |
+| `examples/common-workflows.md` | When the user's request matches a common pattern (end-to-end pipeline setup, inserting a stage, binding an environment, attaching a project, activation) |
+| `scripts/validate-org-type.sh` | Run before `stage environment add` to validate `--org-type` against the `Production`/`Sandbox` enum |
+| `scripts/check-activation-ready.sh` | Run before `pipeline update --activate` to confirm the pipeline has ≥1 stage |
+| `scripts/verify-operation.sh` | Run in Phase 3 to assert a command's JSON status and post-state fields (`status` / `active` / `has-stage` / `has-project`) |