@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/sales-agentforce-pipeline-management-configure/scripts/CHANGES.md

@@ -0,0 +1,180 @@
+# Changes to Force Sales Agent BotDefinition Creation
+
+## Product Context
+
+**Previous behavior**: Pipeline Management had two architectures — "Platform Copilot" (agent user only, backend suggestions work) and "Standalone Bot" (agent user + BotDefinition, interactive chat + backend suggestions). The scripts treated both as valid and would exit successfully with just the agent user.
+
+**Product requirement change**: Users now **require** an interactive Sales Agent they can chat with, which requires the BotDefinition. While backend suggestion generation can technically work with just the agent user + PSG, the complete user experience demands the BotDefinition for conversation interface.
+
+## Problem
+The `create-agent.sh` script previously accepted a "Platform Copilot" architecture where no BotDefinition existed and only backend suggestion generation worked. However, **BotDefinition:SalesAgent is REQUIRED** for a complete Pipeline Management experience — users need an interactive Sales Agent they can chat with. The original script would exit successfully when it found the agent user, even if no BotDefinition existed, leaving users without the required interactive agent.
+
+## Solution
+Modified `create-agent.sh` to **always attempt to create the Sales Agent BotDefinition** when:
+- Agent user exists ✓
+- PSG is assigned ✓
+- **BotDefinition does NOT exist** ❌
+
+## Changes Made to `create-agent.sh`
+
+### Before (Lines 80-93)
+```bash
+if [[ -n "$EXISTING_BOT" ]]; then
+  echo "  Architecture: Standalone Bot (BotDefinition:SalesAgent found)"
+else
+  echo "  Architecture: Platform Copilot (no standalone BotDefinition — this is normal)"
+  echo "  PM actions are wired into the platform-level Copilot agent."
+fi
+echo ""
+echo "Agent setup is FUNCTIONAL."
+# ... exits immediately
+exit 0
+```
+
+**Issue**: Script exits without creating BotDefinition, leaving users with no interactive agent.
+
+### After (Lines 80-165)
+```bash
+if [[ -n "$EXISTING_BOT" ]]; then
+  # BotDefinition exists - done
+  echo "  Architecture: Standalone Bot (BotDefinition:SalesAgent found)"
+  exit 0
+else
+  # BotDefinition missing - create it (REQUIRED)
+  echo "  BotDefinition:SalesAgent not found"
+  echo "  Attempting to create Sales Agent BotDefinition for user interaction..."
+  
+  # Deploy via authoring bundle
+  if ! sf agent publish authoring-bundle --api-name SalesAgent; then
+    echo "ERROR: Failed to publish Sales Agent"
+    exit 1
+  fi
+  
+  # Activate latest version
+  if ! sf agent activate --api-name SalesAgent --version <latest>; then
+    echo "ERROR: Failed to activate Sales Agent"
+    exit 1
+  fi
+  
+  # Success - BotDefinition created and activated
+  exit 0
+fi
+```
+
+**Fix**: Script now:
+1. Detects missing BotDefinition
+2. Deploys Sales Agent via authoring bundle
+3. Activates the agent automatically
+4. **Exits 1 if creation fails** (BotDefinition is required, not optional)
+5. Provides clear success/failure messaging
+
+## New Behavior
+
+### When agent user exists AND BotDefinition exists
+
+```text
+✓ Agent user found
+✓ BotDefinition found
+✓ Agent setup is FUNCTIONAL
+✓ No further action needed
+```
+
+### When agent user exists BUT BotDefinition missing
+
+```text
+✓ Agent user found
+⚠ BotDefinition NOT found
+→ Creating Sales Agent via authoring bundle...
+→ Publishing Sales Agent...
+→ Activating Sales Agent version <latest>...
+✓ Agent setup is COMPLETE
+```
+
+### When agent user is missing
+
+```text
+✗ Agent user NOT found
+→ Attempting SOAP toggle...
+→ (existing fallback logic)
+```
+
+## Testing
+
+To test the modified script:
+
+```bash
+cd skills/sales-agentforce-pipeline-management-configure/scripts
+
+# Test on org with agent user but no BotDefinition
+/opt/homebrew/bin/bash create-agent.sh <org-alias>
+
+# Expected output:
+# - Detects agent user
+# - Detects missing BotDefinition
+# - Creates and activates Sales Agent
+# - Exits with status 0
+```
+
+## Files Modified
+
+1. **`scripts/create-agent.sh`** - Main logic change (lines 80-165)
+   - Added authoring bundle deployment when BotDefinition is missing
+   - Added agent activation step
+   - Added improved status messaging
+
+## Backward Compatibility
+
+✅ **Fully backward compatible**
+- If BotDefinition already exists → same behavior as before (early exit)
+- If agent user is missing → existing fallback logic unchanged
+- Only new behavior is when agent user exists but BotDefinition is missing
+
+## Related Files
+
+- **Assets used**:
+  - `assets/sales_management_agent.agent` - Agent Script definition
+  - `assets/sales_management_agent.bundle-meta.xml` - Bundle metadata
+  
+- **Called from**:
+  - `setup-all.sh` - Main orchestration script (Phase 4)
+
+## Verification
+
+After running the modified script, verify with:
+
+```bash
+/opt/homebrew/bin/bash verify-all.sh <org-alias>
+```
+
+Expected output:
+
+```text
+--- Agent ---
+  [PASS] Agent user: salesmanagementagentuser@...
+  [PASS] BotDefinition: SalesAgent  ← Should now PASS instead of FAIL
+```
+
+## Impact
+
+**Before**: Users had to manually create the Sales Agent BotDefinition  
+**After**: Sales Agent BotDefinition is created automatically
+
+This ensures users get both:
+1. ✅ Backend suggestion generation (agent user + flow)
+2. ✅ Interactive Sales Agent for user chat (BotDefinition)
+
+## Commit Message
+
+```text
+fix: always create Sales Agent BotDefinition in create-agent.sh
+
+When agent user exists but BotDefinition is missing, the script now:
+- Deploys Sales Agent via authoring bundle
+- Activates version 1 automatically
+- Provides clear success/failure messaging
+
+This ensures users get an interactive Sales Agent they can chat with,
+not just backend suggestion generation.
+
+Fixes: Pipeline Management setup completing without user-facing agent
+```

package/skills/sales-agentforce-pipeline-management-configure/scripts/README.md

@@ -0,0 +1,56 @@
+# Scripts for Pipeline Management Configuration
+
+This directory contains automation scripts for enabling Agentforce Pipeline Management. All scripts require an `sfdx-project.json` in your working directory.
+
+## Prerequisites
+
+- Salesforce CLI (`sf`) installed
+- Authenticated org with alias
+- `sfdx-project.json` in working directory (see `../assets/sfdx-project.json`)
+
+## Usage Table
+
+| Script | Purpose | Usage | Dependencies |
+|--------|---------|-------|--------------|
+| `setup-all.sh` | **Master orchestration** — end-to-end setup, enables all prerequisites + PM inline | `./setup-all.sh <org-alias> --fields "NextStep,Risk__c"` | None (auth only) |
+| `retrieve-settings.sh` | Retrieve all settings for inspection | `./retrieve-settings.sh <org-alias>` | None |
+| `enable-prerequisites.sh` | Enable prerequisite settings only (no fields/flow/agent) | `./enable-prerequisites.sh <org-alias>` | None |
+| `enable-deal-agent.sh` | Enable SalesDealAgent settings (standalone helper) | `./enable-deal-agent.sh <org-alias>` | Prerequisites must already be enabled |
+| `create-flow.sh` | Detect/verify/activate suggestion flow | `./create-flow.sh <org-alias>` | Deal agent enabled + manual UI clone |
+| `create-agent.sh` | Verify/create/activate agent | `./create-agent.sh <org-alias>` | Deal agent enabled |
+| `deploy-settings.sh` | Deploy settings from local files | `./deploy-settings.sh <org-alias>` | Local metadata files |
+| `verify-all.sh` | Comprehensive status check | `./verify-all.sh <org-alias>` | None (read-only) |
+
+## Execution Order
+
+For end-to-end setup, drive **`setup-all.sh`** — it enables all prerequisites (Einstein GenAI, Agentforce, Enhanced Notes, Opportunity Team), enables Pipeline Management, deploys prompt templates, builds/activates the flow, provisions the agent + PSGs, and verifies, in dependency order. The individual scripts below are for isolated inspection or repair of a single component:
+
+1. **retrieve-settings.sh** — Inspect current state
+2. **enable-prerequisites.sh** — Enable prerequisite settings only (Einstein, Notes, Opportunity Team)
+3. **enable-deal-agent.sh** — Enable Pipeline Management in isolation (prerequisites must already be on)
+4. **create-flow.sh** — Detect/verify/activate flow (requires manual Setup UI clone first)
+5. **create-agent.sh** — Verify agent user and PSGs (auto-provisioned on enablement)
+6. **verify-all.sh** — Comprehensive status check (read-only)
+
+## Important Notes
+
+- All scripts are idempotent (safe to re-run)
+- Scripts use SOAP API v62.0-64.0 for settings that fail silently via CLI
+- Individual setting deployment isolates failures
+- Each script validates before making changes
+- All `sf` commands use `--json` with error suppression for clean parsing
+
+## sfdx-project.json Requirement
+
+All scripts expect an `sfdx-project.json` in your working directory. Copy from `../assets/sfdx-project.json`:
+
+```bash
+cp ../assets/sfdx-project.json ./sfdx-project.json
+```
+
+## Error Handling
+
+- Scripts exit with non-zero code on critical failures
+- Warnings are logged but don't stop execution
+- SOAP API errors are captured and reported
+- Missing metadata is handled gracefully