@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/sales-call-scoring-configure/references/competency-crud.md

@@ -0,0 +1,130 @@
+# Competency CRUD workflow — Full Spec
+
+Consult this reference whenever the admin's ask touches competency records (list, install, create, edit, activate/deactivate, verify, delete).
+
+Once Phase 5 of `enable-call-scoring.sh` confirms the feature is enabled (or Phase 1 detects State 3/4), Claude runs the `Next:` script from `enable-call-scoring.sh` directly, in the same turn. Records are managed via Tooling API on `EnablementCompetencyDef` (setup entity, keyPrefix `1nA`, module `conversation-udd`). Cap: **8 simultaneously active** per org (`CoachingCompetenciesFeature.MAX_ACTIVE_COMPETENCIES`).
+
+All scripts share `shared/auth.sh` / `resolve_org_auth` (same fail-fast messages, token-reuse across chained invocations). Tooling API writes go through `sf api request rest` where practical; a subset (custom-CRUD variants, best-practice installer) drops to raw `curl` for finer request shape.
+
+**Two parallel families:** generic scripts (`{create,edit,toggle,get}-competency.sh`) work on any competency; custom-CRUD variants (`*-custom-competency.sh`) harden the write path with SpecificCallsOnly filter JSON and richer validation. Prefer the custom variants when the admin's intent is unambiguously custom (S5-created); fall back to generic on OOTB or unknown-provenance records.
+
+## Table of contents
+
+- [S3 · List](#s3--list--list-competenciessh-alias---verbose--json)
+- [S4 · Install OOTB set](#s4--install-ootb-set--install-ootb-competenciessh-alias---dry-run)
+- [S4b · Install best-practice set](#s4b--install-best-practice-set--install-best-practice-competenciessh-alias---dry-run---only-name1name2)
+- [S5 · Create custom (conversational)](#s5--create-custom-conversational--create-custom-competencysh-alias-payloadjson)
+- [S6 · Edit](#s6--edit--edit-competencysh-alias-name-or-id--or-edit-custom-competencysh-alias-name-or-id-)
+- [S7 · Activate/deactivate](#s7--activatedeactivate--toggle-competencysh-alias-name-or-id-activatedeactivate-or-toggle-custom-competencysh-alias-name-or-id-activatedeactivate)
+- [S8 · Fetch a record](#s8--fetch-a-record--get-competencysh-alias-name-or-id---field-name-or-get-custom-competencysh-alias-name-or-id---field-name)
+- [S9 · Verify](#s9--verify--verify-ootb-competenciessh-alias-name-)
+- [S10 · Delete](#s10--delete--no-dedicated-script-yet-use-sf-cli-directly)
+- [Execution sequence — by admin intent × org state](#execution-sequence--by-admin-intent--org-state)
+- [Chaining checkpoints](#chaining-checkpoints-claude-must-respect)
+
+## S3 · List — `list-competencies.sh <alias> [--verbose|--json]`
+
+Enumerates current competencies. Shows `Active / 8 (max)` count.
+
+**Output modes** (per admin-comms rule #5 — admin-safe by default):
+
+- **Default** — `MasterLabel` + `IsActive` icon + `EvaluationScope` + `Description`. **No** record Ids, DeveloperNames, or Template enum keys. Safe to forward directly to the admin.
+- **`--verbose`** — Default fields PLUS `DeveloperName`, `SourceCompetencyTemplate` enum, and `Id`. Use only when the admin explicitly asks to debug or share with support.
+- **`--json`** — Raw record JSON for the calling agent to parse. Never forward this to the admin directly.
+
+## S4 · Install OOTB set — `install-ootb-competencies.sh <alias> [--dry-run]`
+
+Creates the 6 PRD-canonical competencies (Active Listening Skills, Relationship Building, Discovery Questioning, Objection Handling, Value Proposition Focus, Closing Urgency) with prompt bodies taken verbatim from `assets/ootb-competencies.json`. Idempotent: matches by `SourceCompetencyTemplate` and skips already-installed rows.
+
+**`--list` mode** (`install-ootb-competencies.sh --list`) — no org alias, no auth, no write. Renders the 6 competencies (name + what each evaluates) as a markdown table straight from the asset file. This is what backs rule #13's OOTB-vs-custom question: show this table to the admin *before* they decide between the OOTB set and building custom competencies, not after installing.
+
+Checks `IsEciCallScoringEnabled` on `ConversationalIntelligenceSettings` before writing — refuses with a pointer to `enable-call-scoring.sh` if Call Coaching isn't enabled yet, rather than creating competency records the admin can't see or use until it is.
+
+Output is admin-safe by default — no DeveloperName suffixes, Template enum keys, or record Ids leak into per-row lines. When the org is already at the 8-active cap, records land inactive with an "activate later" hint.
+
+**Always follow with S9** on first-time setup — see the S9 carve-out for why the verify table is the one place entity-level detail is surfaced to the admin by design.
+
+## S4b · Install best-practice set — `install-best-practice-competencies.sh <alias> [--dry-run] [--only "Name1,Name2,..."]`
+
+Creates the 7 Momentum best-practice reference prompts from `assets/best-practice-competencies.json` (Business Problem Diagnosis, Change Management Navigation, Discovery Excellence, Executive Vision Alignment, Multi-Stakeholder Orchestration, Product Knowledge, Enterprise Value Articulation). Parallel to S4 but with richer PRD/PURPOSE-structured prompt bodies.
+
+Same idempotency (by `SourceCompetencyTemplate`) and cap-fallback behavior as S4. Use `--only "Name1,Name2"` to install a subset by `MasterLabel`.
+
+## S5 · Create custom (conversational) — `create-custom-competency.sh <alias> <payload.json>`
+
+The bash primitive expects a JSON payload with at minimum `MasterLabel` and `EvaluationInstructions`; optional `Description`, `EvaluationScope` (`AllCalls` | `SpecificCallsOnly`), `EvaluationConditions` (FilterCriteria JSON, required when scope is `SpecificCallsOnly`), `IsActive` (default `true`), `SourceCompetencyTemplate` (leave empty for custom).
+
+**Claude's conversational role — the Q1-Q4 sequence.** When the admin asks to add a custom competency, do NOT jump to drafting. Ask these four in order, one at a time:
+
+- **Q1. What sales skill are you trying to score?** One sentence in the admin's own words. Anchor for the whole competency.
+- **Q2. What does *good* look like on a call?** 2-3 observable, call-audible behaviors (not internal states).
+- **Q3. What does *not good* look like?** 2-3 concrete behaviors indicating the skill is missing or poorly applied, at the same bar.
+- **Q4. Active right now?** Yes → `IsActive=true` (auto-falls back to inactive if org is at the 8-active cap; script prints an "activate later" hint). No → `IsActive=false`.
+
+Do NOT ask about call-filter scope (Enterprise-only, discovery-only, etc.). Competencies apply to all calls today regardless of the `EvaluationScope`/`EvaluationConditions` record fields, so asking creates a false expectation for the admin. The bash primitive still accepts those fields for a future re-enablement — see S5 header — but the conversational flow leaves them defaulted (`AllCalls`) and empty.
+
+After Q1-Q4, draft the `EvaluationInstructions` prompt using the **PURPOSE / KEY AREAS / positive-negative-indicators / EXAMPLE** structure mirrored from `assets/best-practice-competencies.json`. Show the draft to the admin — e.g. "I've put together a draft based on your answers, following the same structure as best practices:" — never "best-practice competencies" in admin-facing text; that's the internal asset/script name, not admin language (rule #6). Iterate once if they request changes, then:
+
+1. Write the payload to a temp JSON file — `MasterLabel` (from Q1's skill name, title-cased), `EvaluationInstructions` (the drafted prompt), `Description` (a 1-sentence version of Q1), `IsActive` (from Q4). Omit `EvaluationScope`/`EvaluationConditions` — the script defaults to `AllCalls`.
+2. Invoke `create-custom-competency.sh <alias> <payload.json>`.
+3. Delete the temp JSON afterwards.
+4. Chain into S9 verify (passing the just-created `MasterLabel`) to confirm and show the admin what got configured.
+
+**Do not skip Q1-Q4.** The eval-readiness bar requires that admins go through a structured authoring flow, not a "just draft me something for X" one-shot. If the admin insists on skipping, still capture the minimum needed for `MasterLabel` + `EvaluationInstructions` — but push back once.
+
+## S6 · Edit — `edit-competency.sh <alias> <name-or-id> ...` OR `edit-custom-competency.sh <alias> <name-or-id> ...`
+
+Both take `--instructions[-file] <>` and/or `--description <>`. PATCH updates preserve Id, DeveloperName, IsActive, EvaluationScope, SourceCompetencyTemplate. Enforce 16000 / 255 char field caps.
+
+Prefer `edit-custom-competency.sh` for competencies created via S5; use `edit-competency.sh` on OOTB or unknown-provenance competencies.
+
+## S7 · Activate/deactivate — `toggle-competency.sh <alias> <name-or-id> <activate|deactivate>` OR `toggle-custom-competency.sh <alias> <name-or-id> <activate|deactivate>`
+
+Flips `IsActive`. Idempotent. Enforces the 8-active cap on the activate path — refuses to activate if the org is at cap and prints the current active set so the admin can choose which to deactivate. Deactivation preserves historical `EnablementCompetencyEval` records per the entity XML comment. Same generic-vs-custom split as S6.
+
+## S8 · Fetch a record — `get-competency.sh <alias> <name-or-id> [--field <name>]` OR `get-custom-competency.sh <alias> <name-or-id> [--field <name>]`
+
+Returns the full record (or a single field) so Claude can load the current `EvaluationInstructions` into context before drafting an improvement. Conversational improvement suggestions are Claude's job (see S5 for the reference-prompt library); the resulting write is done via `edit-competency.sh` / `edit-custom-competency.sh`.
+
+## S9 · Verify — `verify-ootb-competencies.sh <alias> ["Name" ...]`
+
+Confirms expected competencies exist and are active, printing name + evaluation criteria in a markdown table. Run after S4 / S4b / S5 to catch partial installs. No args → full 6-competency OOTB set from `assets/ootb-competencies.json`; explicit `MasterLabel` values → verify a specific subset. Exits 0 only if every expected name exists AND `IsActive=true`.
+
+**Carve-out to admin-comms rules #5 and #6.** The S9 table is the ONE place prompt-body content (`EvaluationInstructions`) is deliberately surfaced to the admin — after an install, the admin needs to see the actual names and evaluation criteria, not just a count. On first-time setup, paste the script's table output directly into the chat response. Column labels ("Competency", "Evaluation Instructions") are admin English, not raw entity API names.
+
+## S10 · Delete — no dedicated script (yet); use `sf` CLI directly
+
+No `delete-competency.sh` yet. Resolve the Id via `list-competencies.sh --verbose` (don't expose it to the admin), then:
+
+```bash
+sf data delete record --sobject EnablementCompetencyDef --record-id <Id> \
+  --target-org <alias> --use-tooling-api
+```
+
+Report "Deleted '<MasterLabel>'" — not the Id.
+
+**Caveats.** FK-referenced records cannot be deleted — if the competency has `EnablementCompetencyEval` rows attached, DELETE fails on foreign-key constraint; use `toggle-*-competency.sh deactivate` instead (preserves history per the entity XML comment). When in doubt, deactivate first via S7 — frees the active slot even if the subsequent delete fails on FK.
+
+## Execution sequence — by admin intent × org state
+
+Once Phase 1 classifies the org into State 1a / 2 / 3 / 4, the intent × state matrix below determines which scripts to chain, in what order. **Chain automatically per rule #12** — do not ask permission between steps.
+
+| Admin intent | State 1a (no ECI) | State 2 (avail, not enabled) | State 3 (enabled, no comps) | State 4 (enabled, with comps) |
+|---|---|---|---|---|
+| **Enable Call Coaching** (unqualified — no OOTB/custom stated) | Refuse — needs Agentforce for Sales | `enable-call-scoring.sh` → rule #13 ask (OOTB vs custom) | Idempotent — rule #13 ask (OOTB vs custom) | Idempotent — `enable-call-scoring.sh` exits 0, chains into S3 list |
+| **Install OOTB set** (explicitly asked) | (refuse) | `enable-call-scoring.sh` auto-chains into S4 → S9 | `install-ootb-competencies.sh` → S9 | `install-ootb-competencies.sh` (idempotent — skips existing templates) → S9 |
+| **Install best-practice set** | (refuse) | `enable-call-scoring.sh` → `install-best-practice-competencies.sh` → S9 | `install-best-practice-competencies.sh` → S9 | `install-best-practice-competencies.sh` (idempotent) → S9 |
+| **Create custom competency** | (refuse) | `enable-call-scoring.sh` → **Q1-Q4** → `create-custom-competency.sh` → S9 | **Q1-Q4** → `create-custom-competency.sh` → S9 | **Q1-Q4** → `create-custom-competency.sh` → S9 |
+| **Edit competency** | (refuse) | (no competencies to edit) | (no competencies to edit) | `edit-competency.sh` (OOTB) OR `edit-custom-competency.sh` (custom) |
+| **Activate / deactivate** | (refuse) | (n/a) | (n/a) | `toggle-competency.sh` OR `toggle-custom-competency.sh` |
+| **Improve a competency's prompt** | (refuse) | (n/a) | (n/a) | `get-*-competency.sh` (load current) → draft (Claude) → `edit-*-competency.sh` |
+| **List / audit** | (refuse) | `list-competencies.sh` (empty) | `list-competencies.sh` (empty) | `list-competencies.sh` |
+| **Verify OOTB set installed** | (refuse) | (nothing to verify) | (refuse — nothing installed) | `verify-ootb-competencies.sh` |
+| **Delete a competency** | (refuse) | (n/a) | (n/a) | S10 — `sf data delete record` (fall back to S7 deactivate if FK-blocked) |
+
+## Chaining checkpoints Claude must respect
+
+- `enable-call-scoring.sh` prints `Next: <script>` on stdout — that's a hard chain hint. Run it in the same turn without asking (rule #12), **except** the State 3 hint, which points at `install-ootb-competencies.sh --list` — render that table and ask OOTB-vs-custom (rule #13) before writing anything, unless the admin's original ask already named one.
+- After S4 / S4b / S5, always run S9 verify. Paste its table to the admin (S9 carve-out).
+- After S5, do NOT stop at "created" — always show the admin what got created via S9.
+- Between chained scripts, `ACCESS_TOKEN` and `INSTANCE_URL` propagate through the shared shell env (per Phase 0) — no re-auth.

package/skills/sales-call-scoring-configure/scripts/create-competency.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+
+# Create a single custom Coaching Competency from a JSON payload.
+# Payload must contain: MasterLabel, EvaluationInstructions.
+# Optional: DeveloperName (auto-generated if omitted), Description,
+# EvaluationScope (defaults AllCalls), IsActive (defaults true),
+# SourceCompetencyTemplate (empty for custom).
+#
+# This is the deterministic write primitive for S5 (custom conversational
+# competency creation). Claude drives the conversational drafting;
+# once the prompt is approved, it writes the payload to a temp JSON and
+# invokes this script.
+#
+# Usage: ./create-competency.sh <org-alias> <payload.json>
+
+set -euo pipefail
+
+export NO_COLOR=1
+export FORCE_COLOR=0
+
+ORG_ALIAS="${1:-}"
+PAYLOAD_FILE="${2:-}"
+
+if [[ -z "$ORG_ALIAS" || -z "$PAYLOAD_FILE" ]]; then
+  echo "Usage: $0 <org-alias> <payload.json>"
+  exit 1
+fi
+if [[ ! -f "$PAYLOAD_FILE" ]]; then
+  echo "Payload file not found: $PAYLOAD_FILE"
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Validate payload
+# ---------------------------------------------------------------------------
+MASTER_LABEL=$(jq -r '.MasterLabel // empty' "$PAYLOAD_FILE")
+INSTRUCTIONS=$(jq -r '.EvaluationInstructions // empty' "$PAYLOAD_FILE")
+
+if [[ -z "$MASTER_LABEL" ]]; then echo "MasterLabel is required"; exit 1; fi
+if [[ -z "$INSTRUCTIONS" ]]; then echo "EvaluationInstructions is required"; exit 1; fi
+
+INSTR_LEN=${#INSTRUCTIONS}
+if [[ "$INSTR_LEN" -gt 16000 ]]; then
+  echo "EvaluationInstructions is $INSTR_LEN chars — max 16000"
+  exit 1
+fi
+
+DESCRIPTION=$(jq -r '.Description // ""' "$PAYLOAD_FILE")
+DESC_LEN=${#DESCRIPTION}
+if [[ "$DESC_LEN" -gt 255 ]]; then
+  echo "Description is $DESC_LEN chars — max 255"
+  exit 1
+fi
+
+SCOPE=$(jq -r '.EvaluationScope // "AllCalls"' "$PAYLOAD_FILE")
+if [[ "$SCOPE" != "AllCalls" && "$SCOPE" != "SpecificCallsOnly" ]]; then
+  echo "EvaluationScope must be AllCalls or SpecificCallsOnly (got: $SCOPE)"
+  exit 1
+fi
+
+# jq's // treats false as absent; use explicit null-check to preserve IsActive:false.
+IS_ACTIVE=$(jq -r 'if has("IsActive") then .IsActive else true end' "$PAYLOAD_FILE")
+TEMPLATE=$(jq -r '.SourceCompetencyTemplate // ""' "$PAYLOAD_FILE")
+DEV_NAME=$(jq -r '.DeveloperName // empty' "$PAYLOAD_FILE")
+
+if [[ -z "$DEV_NAME" ]]; then
+  SANITIZED=$(echo "$MASTER_LABEL" | tr -cd '[:alnum:]' | cut -c1-30)
+  SUFFIX=$(hexdump -n 3 -e '"%06x"' /dev/urandom)
+  DEV_NAME="CCH_${SANITIZED}_${SUFFIX}"
+fi
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=shared/auth.sh
+source "$SCRIPT_DIR/shared/auth.sh"
+
+resolve_org_auth "$ORG_ALIAS" || exit 1
+
+TOOLING_BASE="services/data/v68.0/tooling"
+
+# ---------------------------------------------------------------------------
+# 8-active cap: auto-fallback to inactive so the admin's work isn't blocked.
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=shared/cap.sh
+source "$SCRIPT_DIR/shared/cap.sh"
+# shellcheck source=shared/soql.sh
+source "$SCRIPT_DIR/shared/soql.sh"
+
+CAP_FELL_BACK="false"
+if [[ "$IS_ACTIVE" == "true" ]]; then
+  ACTIVE_COUNT=$( (sf api request rest \
+    "${TOOLING_BASE}/query/?q=SELECT+COUNT()+FROM+EnablementCompetencyDef+WHERE+IsActive=true" \
+    --target-org "$ORG_ALIAS" 2>/dev/null || true) | jq -r '.totalSize // 0' 2>/dev/null)
+  ACTIVE_COUNT="${ACTIVE_COUNT:-0}"
+  if [[ "$ACTIVE_COUNT" -ge "$MAX_ACTIVE_COMPETENCIES" ]]; then
+    echo "Warning: Org is at the 8-active competency cap — creating this one as inactive."
+    echo "   Deactivate an existing competency, then re-activate this one to promote it."
+    IS_ACTIVE="false"
+    CAP_FELL_BACK="true"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Uniqueness check by MasterLabel (to avoid silent duplicates)
+# ---------------------------------------------------------------------------
+LABEL_ENC=$(printf "SELECT Id FROM EnablementCompetencyDef WHERE MasterLabel='%s'" "$(soql_escape "$MASTER_LABEL")" | jq -sRr @uri)
+DUP=$( (sf api request rest "${TOOLING_BASE}/query/?q=${LABEL_ENC}" --target-org "$ORG_ALIAS" 2>/dev/null || true) \
+  | jq -r '.totalSize // 0' 2>/dev/null)
+DUP="${DUP:-0}"
+if [[ "$DUP" != "0" ]]; then
+  echo "A competency with MasterLabel '$MASTER_LABEL' already exists — refusing to duplicate."
+  echo "   Use edit-competency.sh to update, or choose a different name."
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Build final payload + POST
+# ---------------------------------------------------------------------------
+FINAL=$(jq -n \
+  --arg mn "$MASTER_LABEL" \
+  --arg dn "$DEV_NAME" \
+  --arg tp "$TEMPLATE" \
+  --arg de "$DESCRIPTION" \
+  --arg ei "$INSTRUCTIONS" \
+  --arg sc "$SCOPE" \
+  --argjson ia "$IS_ACTIVE" \
+  '{
+     MasterLabel: $mn,
+     DeveloperName: $dn,
+     Description: $de,
+     EvaluationInstructions: $ei,
+     EvaluationScope: $sc,
+     IsActive: $ia
+   } + (if $tp == "" then {} else {SourceCompetencyTemplate: $tp} end)')
+
+echo "Creating: $MASTER_LABEL"
+# No DeveloperName / char count / entity-field leak — rule #5. Scope is
+# admin-facing content ("AllCalls" / "SpecificCallsOnly") so it stays.
+echo "   Scope: $SCOPE   Active: $IS_ACTIVE"
+
+RESP=$(sf api request rest "${TOOLING_BASE}/sobjects/EnablementCompetencyDef" \
+  --target-org "$ORG_ALIAS" \
+  --method POST \
+  --header 'Content-Type: application/json' \
+  --body "$FINAL" \
+  2>/dev/null) || true
+
+if echo "$RESP" | jq -e '.success == true' >/dev/null 2>&1; then
+  NEW_ID=$(echo "$RESP" | jq -r '.id')
+  # No record Id leak on the primary success line — rule #5. Cap-fallback
+  # hint helper prints the activate-later reminder without exposing the Id.
+  if [[ "$CAP_FELL_BACK" == "true" ]]; then
+    echo "Created inactive (8-active cap), activate later"
+    print_cap_footer_activate_hint "$NEW_ID"
+  else
+    echo "Created"
+  fi
+  exit 0
+else
+  echo "Error: Create failed:"
+  echo "$RESP" | jq -c '.' 2>/dev/null || echo "$RESP"
+  exit 1
+fi

package/skills/sales-call-scoring-configure/scripts/create-custom-competency.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+# sales_call_scoring: story="custom-competency-crud" owner="W-CUSTOM-CRUD"
+#
+# Create a custom Coaching Competency from a JSON payload. Companion write
+# primitive for the custom-competency story (S5). Parallel to the generic
+# create-competency.sh; kept as its own file so the custom-CRUD story can
+# harden the write path (SpecificCallsOnly filter JSON, richer validation)
+# without touching the OOTB-owned install script.
+#
+# The prompt body in EvaluationInstructions is intentionally NOT a default —
+# callers supply the full PRD/PURPOSE-structured prompt (see
+# assets/best-practice-competencies.json for reference shape).
+#
+# Required fields:  MasterLabel, EvaluationInstructions
+# Optional fields:  DeveloperName (auto-gen), Description, EvaluationScope
+#                   (AllCalls|SpecificCallsOnly, default AllCalls),
+#                   EvaluationConditions (required when SpecificCallsOnly),
+#                   IsActive (default true),
+#                   SourceCompetencyTemplate (leave empty for custom).
+#
+# Usage: ./create-custom-competency.sh <org-alias> <payload.json>
+
+set -euo pipefail
+
+export NO_COLOR=1
+export FORCE_COLOR=0
+
+ORG_ALIAS="${1:-}"
+PAYLOAD_FILE="${2:-}"
+
+if [[ -z "$ORG_ALIAS" || -z "$PAYLOAD_FILE" ]]; then
+  echo "Usage: $0 <org-alias> <payload.json>"
+  exit 1
+fi
+if [[ ! -f "$PAYLOAD_FILE" ]]; then
+  echo "Payload file not found: $PAYLOAD_FILE"
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Validate payload
+# ---------------------------------------------------------------------------
+MASTER_LABEL=$(jq -r '.MasterLabel // empty' "$PAYLOAD_FILE")
+INSTRUCTIONS=$(jq -r '.EvaluationInstructions // empty' "$PAYLOAD_FILE")
+
+if [[ -z "$MASTER_LABEL" ]]; then echo "MasterLabel is required"; exit 1; fi
+if [[ -z "$INSTRUCTIONS" ]]; then echo "EvaluationInstructions is required"; exit 1; fi
+
+INSTR_LEN=${#INSTRUCTIONS}
+if [[ "$INSTR_LEN" -gt 16000 ]]; then
+  echo "EvaluationInstructions is $INSTR_LEN chars — max 16000"
+  exit 1
+fi
+
+DESCRIPTION=$(jq -r '.Description // ""' "$PAYLOAD_FILE")
+DESC_LEN=${#DESCRIPTION}
+if [[ "$DESC_LEN" -gt 255 ]]; then
+  echo "Description is $DESC_LEN chars — max 255"
+  exit 1
+fi
+
+SCOPE=$(jq -r '.EvaluationScope // "AllCalls"' "$PAYLOAD_FILE")
+if [[ "$SCOPE" != "AllCalls" && "$SCOPE" != "SpecificCallsOnly" ]]; then
+  echo "EvaluationScope must be AllCalls or SpecificCallsOnly (got: $SCOPE)"
+  exit 1
+fi
+
+# jq's // treats false as absent; use explicit null-check to preserve IsActive:false.
+IS_ACTIVE=$(jq -r 'if has("IsActive") then .IsActive else true end' "$PAYLOAD_FILE")
+TEMPLATE=$(jq -r '.SourceCompetencyTemplate // ""' "$PAYLOAD_FILE")
+DEV_NAME=$(jq -r '.DeveloperName // empty' "$PAYLOAD_FILE")
+
+if [[ -z "$DEV_NAME" ]]; then
+  SANITIZED=$(echo "$MASTER_LABEL" | tr -cd '[:alnum:]' | cut -c1-30)
+  SUFFIX=$(hexdump -n 3 -e '"%06x"' /dev/urandom)
+  DEV_NAME="CCH_${SANITIZED}_${SUFFIX}"
+fi
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=shared/auth.sh
+source "$SCRIPT_DIR/shared/auth.sh"
+
+resolve_org_auth "$ORG_ALIAS" || exit 1
+
+TOOLING_BASE="services/data/v68.0/tooling"
+
+# ---------------------------------------------------------------------------
+# 8-active cap: auto-fallback to inactive so the admin's work isn't blocked.
+# ---------------------------------------------------------------------------
+# shellcheck source=shared/cap.sh
+source "$SCRIPT_DIR/shared/cap.sh"
+# shellcheck source=shared/soql.sh
+source "$SCRIPT_DIR/shared/soql.sh"
+
+CAP_FELL_BACK="false"
+if [[ "$IS_ACTIVE" == "true" ]]; then
+  ACTIVE_COUNT=$(query_active_count "$ORG_ALIAS")
+  if [[ "$ACTIVE_COUNT" -ge "$MAX_ACTIVE_COMPETENCIES" ]]; then
+    print_cap_report "$ORG_ALIAS" "creating '$MASTER_LABEL'"
+    IS_ACTIVE="false"
+    CAP_FELL_BACK="true"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Uniqueness check by MasterLabel (to avoid silent duplicates)
+# ---------------------------------------------------------------------------
+LABEL_ENC=$(printf "SELECT Id FROM EnablementCompetencyDef WHERE MasterLabel='%s'" "$(soql_escape "$MASTER_LABEL")" | jq -sRr @uri)
+DUP=$( (sf api request rest "${TOOLING_BASE}/query/?q=${LABEL_ENC}" --target-org "$ORG_ALIAS" 2>/dev/null || true) \
+  | jq -r '.totalSize // 0' 2>/dev/null)
+DUP="${DUP:-0}"
+if [[ "$DUP" != "0" ]]; then
+  echo "A competency with MasterLabel '$MASTER_LABEL' already exists — refusing to duplicate."
+  echo "   Use edit-custom-competency.sh to update, or choose a different name."
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Build final payload + POST
+# ---------------------------------------------------------------------------
+FINAL=$(jq -n \
+  --arg mn "$MASTER_LABEL" \
+  --arg dn "$DEV_NAME" \
+  --arg tp "$TEMPLATE" \
+  --arg de "$DESCRIPTION" \
+  --arg ei "$INSTRUCTIONS" \
+  --arg sc "$SCOPE" \
+  --argjson ia "$IS_ACTIVE" \
+  '{
+     MasterLabel: $mn,
+     DeveloperName: $dn,
+     Description: $de,
+     EvaluationInstructions: $ei,
+     EvaluationScope: $sc,
+     IsActive: $ia
+   } + (if $tp == "" then {} else {SourceCompetencyTemplate: $tp} end)')
+
+echo "Creating: $MASTER_LABEL"
+# No DeveloperName / char count / entity-field leak — rule #5.
+echo "   Scope: $SCOPE   Active: $IS_ACTIVE"
+
+RESP=$(sf api request rest "${TOOLING_BASE}/sobjects/EnablementCompetencyDef" \
+  --target-org "$ORG_ALIAS" \
+  --method POST \
+  --header 'Content-Type: application/json' \
+  --body "$FINAL" \
+  2>/dev/null) || true
+
+if echo "$RESP" | jq -e '.success == true' >/dev/null 2>&1; then
+  NEW_ID=$(echo "$RESP" | jq -r '.id')
+  # No record Id leak — rule #5.
+  if [[ "$CAP_FELL_BACK" == "true" ]]; then
+    echo "Created inactive (8-active cap), activate later"
+    print_cap_footer_activate_hint "$NEW_ID"
+  else
+    echo "Created"
+  fi
+  exit 0
+else
+  echo "Error: Create failed:"
+  echo "$RESP" | jq -c '.' 2>/dev/null || echo "$RESP"
+  exit 1
+fi

package/skills/sales-call-scoring-configure/scripts/edit-competency.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+
+# Edit a Coaching Competency's MasterLabel (display name), Description,
+# and/or EvaluationInstructions.
+# Preserves Id, DeveloperName, IsActive, EvaluationScope, SourceCompetencyTemplate.
+#
+# --label renames the admin-facing display name (MasterLabel). DeveloperName
+# is NOT renamed — it's the API name used by any downstream references and
+# would risk breaking integrations to change. If you need a new
+# DeveloperName, deactivate + create a fresh record.
+#
+# Usage:
+#   ./edit-competency.sh <org-alias> <name-or-id> --label "<new-label>"
+#   ./edit-competency.sh <org-alias> <name-or-id> --instructions-file <file>
+#   ./edit-competency.sh <org-alias> <name-or-id> --description "<new-desc>"
+#   ./edit-competency.sh <org-alias> <name-or-id> --instructions "<literal>"  # short text only
+#   (combine flags to update multiple fields at once)
+
+set -euo pipefail
+
+export NO_COLOR=1
+export FORCE_COLOR=0
+
+ORG_ALIAS="${1:-}"
+IDENT="${2:-}"
+shift 2 || true
+
+if [[ -z "$ORG_ALIAS" || -z "$IDENT" ]]; then
+  echo "Usage: $0 <org-alias> <name-or-id> [--label \"<text>\"] [--instructions-file <file>] [--description \"<text>\"] [--instructions \"<text>\"]"
+  exit 1
+fi
+
+NEW_LABEL=""
+NEW_INSTRUCTIONS=""
+NEW_DESCRIPTION=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --label)
+      NEW_LABEL="$2"
+      shift 2
+      ;;
+    --instructions-file)
+      if [[ ! -f "$2" ]]; then
+        echo "File not found: $2"; exit 1
+      fi
+      NEW_INSTRUCTIONS=$(cat "$2")
+      shift 2
+      ;;
+    --instructions)
+      NEW_INSTRUCTIONS="$2"
+      shift 2
+      ;;
+    --description)
+      NEW_DESCRIPTION="$2"
+      shift 2
+      ;;
+    *)
+      echo "Error: Unknown flag: $1"; exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$NEW_LABEL" && -z "$NEW_INSTRUCTIONS" && -z "$NEW_DESCRIPTION" ]]; then
+  echo "Nothing to update — pass --label, --instructions[-file], and/or --description"
+  exit 1
+fi
+
+if [[ -n "$NEW_LABEL" ]]; then
+  LEN=${#NEW_LABEL}
+  # MasterLabel is a standard platform label field, capped at 80 chars.
+  if [[ "$LEN" -gt 80 ]]; then
+    echo "MasterLabel is ${LEN} chars — max is 80."
+    exit 1
+  fi
+fi
+
+if [[ -n "$NEW_INSTRUCTIONS" ]]; then
+  LEN=${#NEW_INSTRUCTIONS}
+  if [[ "$LEN" -gt 16000 ]]; then
+    echo "EvaluationInstructions is ${LEN} chars — max is 16000."
+    exit 1
+  fi
+fi
+
+if [[ -n "$NEW_DESCRIPTION" ]]; then
+  LEN=${#NEW_DESCRIPTION}
+  if [[ "$LEN" -gt 255 ]]; then
+    echo "Description is ${LEN} chars — max is 255."
+    exit 1
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=shared/auth.sh
+source "$SCRIPT_DIR/shared/auth.sh"
+# shellcheck source=shared/soql.sh
+source "$SCRIPT_DIR/shared/soql.sh"
+
+resolve_org_auth "$ORG_ALIAS" || exit 1
+
+TOOLING_BASE="services/data/v68.0/tooling"
+
+# ---------------------------------------------------------------------------
+# Resolve identifier
+# ---------------------------------------------------------------------------
+if [[ "$IDENT" =~ ^1nA[0-9a-zA-Z]{12,15}$ ]]; then
+  WHERE="Id='${IDENT}'"
+else
+  SAFE=$(soql_escape "$IDENT")
+  WHERE="DeveloperName='${SAFE}' OR MasterLabel='${SAFE}'"
+fi
+QUERY_ENC=$(printf 'SELECT Id,MasterLabel,IsActive FROM EnablementCompetencyDef WHERE %s' "$WHERE" | jq -sRr @uri)
+LOOKUP=$(sf api request rest "${TOOLING_BASE}/query/?q=${QUERY_ENC}" --target-org "$ORG_ALIAS" 2>/dev/null) || true
+RC=$(echo "$LOOKUP" | jq -r '.totalSize // 0')
+
+if [[ "$RC" == "0" ]]; then echo "No competency matched: $IDENT"; exit 1; fi
+if [[ "$RC" != "1" ]]; then
+  echo "Multiple competencies matched '$IDENT' — refusing to bulk-edit."
+  echo "$LOOKUP" | jq -r '.records[] | "   \(.Id)  \(.MasterLabel)"'
+  exit 1
+fi
+
+REC_ID=$(echo "$LOOKUP" | jq -r '.records[0].Id')
+REC_LABEL=$(echo "$LOOKUP" | jq -r '.records[0].MasterLabel')
+REC_ACTIVE=$(echo "$LOOKUP" | jq -r '.records[0].IsActive')
+
+echo "$REC_LABEL ($REC_ID) — IsActive=$REC_ACTIVE"
+
+# ---------------------------------------------------------------------------
+# Uniqueness gate for rename — mirrors the same check create-competency.sh
+# already runs on create, so a rename can't silently collide with an
+# existing label. Excludes the target record's own Id so no-op renames
+# don't self-collide.
+# ---------------------------------------------------------------------------
+if [[ -n "$NEW_LABEL" && "$NEW_LABEL" != "$REC_LABEL" ]]; then
+  LABEL_ENC=$(printf "SELECT Id FROM EnablementCompetencyDef WHERE MasterLabel='%s' AND Id!='%s'" \
+    "$(soql_escape "$NEW_LABEL")" "$REC_ID" | jq -sRr @uri)
+  DUP=$( (sf api request rest "${TOOLING_BASE}/query/?q=${LABEL_ENC}" --target-org "$ORG_ALIAS" 2>/dev/null || true) \
+    | jq -r '.totalSize // 0' 2>/dev/null)
+  DUP="${DUP:-0}"
+  if [[ "$DUP" != "0" ]]; then
+    echo "Another competency already uses label '$NEW_LABEL' — refusing to duplicate."
+    echo "   Choose a different label, or edit the existing record instead."
+    exit 1
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Build PATCH payload
+# ---------------------------------------------------------------------------
+PAYLOAD='{}'
+if [[ -n "$NEW_LABEL" ]]; then
+  PAYLOAD=$(echo "$PAYLOAD" | jq --arg v "$NEW_LABEL" '. + {MasterLabel: $v}')
+fi
+if [[ -n "$NEW_INSTRUCTIONS" ]]; then
+  PAYLOAD=$(echo "$PAYLOAD" | jq --arg v "$NEW_INSTRUCTIONS" '. + {EvaluationInstructions: $v}')
+fi
+if [[ -n "$NEW_DESCRIPTION" ]]; then
+  PAYLOAD=$(echo "$PAYLOAD" | jq --arg v "$NEW_DESCRIPTION" '. + {Description: $v}')
+fi
+
+if RESP_BODY=$(sf api request rest "${TOOLING_BASE}/sobjects/EnablementCompetencyDef/${REC_ID}" \
+  --target-org "$ORG_ALIAS" \
+  --method PATCH \
+  --header 'Content-Type: application/json' \
+  --body "$PAYLOAD" \
+  2>/dev/null); then
+  # Show the new label if renamed, since the pre-rename $REC_LABEL is now stale.
+  if [[ -n "$NEW_LABEL" && "$NEW_LABEL" != "$REC_LABEL" ]]; then
+    echo "Renamed '$REC_LABEL' → '$NEW_LABEL'"
+  else
+    echo "Updated $REC_LABEL"
+  fi
+  [[ -n "$NEW_INSTRUCTIONS" ]] && echo "   EvaluationInstructions: ${#NEW_INSTRUCTIONS} chars"
+  [[ -n "$NEW_DESCRIPTION" ]]  && echo "   Description:            ${#NEW_DESCRIPTION} chars"
+  exit 0
+else
+  echo "Error: PATCH failed"
+  echo "   $RESP_BODY"
+  exit 1
+fi