@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/developing-agentforce/references/architecture-patterns.md

@@ -1,158 +0,0 @@
-# Architecture Patterns
-
-> Extracted from SKILL.md Section 8. This file is loaded on demand when architecture pattern guidance is needed.
-
-> All architecture patterns below work for both `AgentforceServiceAgent` and `AgentforceEmployeeAgent`. The only difference is that employee agents cannot use `@utils.escalate` or `connection messaging:` — replace escalation with a `@utils.transition` to a help subagent or an action that creates a case/ticket.
-
-## When to Use Each Pattern
-
-| Pattern | Use When |
-|---------|----------|
-| Hub-and-Spoke | Agent has 2+ distinct subagents with different intents (most common) |
-| Verification Gate | Sensitive data, payments, or PII require identity verification first |
-| Post-Action Loop | Actions produce state that drives follow-up logic (e.g., risk scoring) |
-| Single Subagent | Agent serves one focused purpose with no routing needed |
-
-## Hub-and-Spoke (Most Common)
-
-A central `agent_router` routes to specialized spoke subagents. Each spoke has a "back to hub" transition. Use when users may have multiple distinct intents.
-
-```
-start_agent agent_router:
-	description: "Route user requests to the appropriate subagent"
-	reasoning:
-		instructions: |
-			You are a router only. Do NOT answer questions directly.
-			Always use a transition action to route immediately.
-		actions:
-			to_orders: @utils.transition to @subagent.order_support
-				description: "Order questions"
-			to_returns: @utils.transition to @subagent.return_support
-				description: "Return or refund requests"
-			to_general: @utils.transition to @subagent.general_support
-				description: "General questions"
-
-subagent order_support:
-	description: "Handle order inquiries"
-	reasoning:
-		instructions: ->
-			| Help the customer with their order.
-		actions:
-			lookup: @actions.get_order
-				description: "Look up order"
-			back: @utils.transition to @subagent.agent_router
-				description: "Route to a different subagent"
-```
-
-> **Routing lives in `start_agent`** -- put all transition actions directly in `start_agent agent_router:`. Do NOT create a separate routing-only subagent (e.g. `main_menu`, `central_hub`) -- that duplicates the router, adds an extra LLM hop (~3-5s latency), and confuses the platform. Subagents that need "go back" should transition to `@subagent.agent_router`.
-
-## Verification Gate
-
-Users must pass through identity verification before accessing protected subagents. Use when handling sensitive data, payments, or PII.
-
-```
-start_agent agent_router:
-	description: "Route through identity verification"
-	reasoning:
-		instructions: |
-			You are a router only. Do NOT answer questions directly.
-			Route all users to identity verification first.
-		actions:
-			verify: @utils.transition to @subagent.identity_verification
-				description: "Begin verification"
-
-subagent identity_verification:
-	description: "Verify customer identity"
-	reasoning:
-		instructions: ->
-			if @variables.failed_attempts >= 3:
-				| Too many failed attempts. Transferring to human agent.
-				transition to @subagent.escalation
-
-			if @variables.is_verified == True:
-				| Identity verified! How can I help?
-
-			if @variables.is_verified == False:
-				| Please verify your identity.
-
-		actions:
-			verify_email: @actions.verify_identity
-				description: "Verify customer email"
-				set @variables.is_verified = @outputs.verified
-
-			to_account: @utils.transition to @subagent.account_mgmt
-				description: "Account management"
-				available when @variables.is_verified == True
-
-			escalate_now: @utils.escalate
-				description: "Transfer to human"
-```
-
-## Post-Action Loop
-
-The subagent re-resolves after an action completes. Place post-action checks at the TOP of `instructions: ->` so they trigger on the loop:
-
-```
-reasoning:
-	instructions: ->
-		# POST-ACTION CHECK (at TOP - triggers on re-resolution)
-		if @variables.refund_status == "Approved":
-			run @actions.create_crm_case
-				with customer_id = @variables.customer_id
-			transition to @subagent.confirmation
-
-		# PRE-LLM: Load data
-		run @actions.load_risk_score
-			with customer_id = @variables.customer_id
-			set @variables.risk_score = @outputs.score
-
-		# DYNAMIC INSTRUCTIONS
-		| Risk score: {!@variables.risk_score}
-		if @variables.risk_score >= 80:
-			| HIGH RISK - Offer retention package.
-		else:
-			| STANDARD - Follow normal process.
-```
-
-## Migrating to Hub-and-Spoke
-
-When refactoring a flat agent (all logic in one subagent) into hub-and-spoke:
-
-1. **Identify distinct intents** — each becomes a spoke subagent
-2. **Move instructions and actions** from the monolithic subagent into spoke subagents. Each spoke needs BOTH its Level 1 action definitions (under `subagent > actions`) AND Level 2 action invocations (under `subagent > reasoning > actions`).
-3. **Create `start_agent agent_router:`** with transition actions pointing to each spoke
-4. **Add "back to hub" transitions** in each spoke: `@utils.transition to @subagent.agent_router`
-5. **Re-preview immediately** — verify subagent routing works before making further changes
-
-**Common migration mistakes:**
-- Creating a separate `main_menu` subagent instead of using `start_agent agent_router:` as the hub — adds an unnecessary LLM hop
-- Leaving action definitions in `start_agent` instead of moving them to spoke subagents — all actions visible in all subagents, confusing the planner
-- Forgetting to add "back to hub" transitions — users get stuck in a spoke subagent
-- If trace shows `topic: "DefaultTopic"`, check that subagent descriptions contain keywords matching test utterances
-
-## Multi-Intent Handling
-
-When a user sends multiple intents in one message, the start_agent router should handle the first intent and queue the second:
-
-```
-instructions: |
-	You are a router only. Do NOT answer questions directly.
-	If the user asks about multiple subagents in one message, route to the first
-	subagent. After that task is complete, remind the user about the other request.
-```
-
-## Handling Incomplete Action Inputs
-
-- Use `with param = ...` (slot-fill) for inputs the LLM should extract from conversation
-- Add instructions that tell the LLM to invoke the action with whatever data is available
-- Anti-pattern: Making the LLM ask for ALL inputs before invoking
-
-## Controlling Opportunistic Action Chains
-
-In long action chains (A->B->C->D), the LLM may invoke downstream actions as soon as prerequisites are met. To control this:
-
-- Add explicit gating in instructions: "Only invoke generate_resolution if the user explicitly asks"
-- Use `available when` guards on downstream actions
-- Distinguish between "analyze only" and "full resolution" workflows in instructions
-
-Anti-pattern: Leaving action chains ungated so the LLM runs the entire pipeline for every query.

package/skills/developing-agentforce/references/complex-data-types.md

@@ -1,57 +0,0 @@
-<!-- Parent: adlc-author/SKILL.md -->
-
-# `complex_data_type_name` Mapping Table
-
-> **"#1 source of compile errors"** - Use this table when defining action inputs/outputs in Agentforce Assets.
-
-## Decision Tree: When Do I Need `complex_data_type_name`?
-
-1. **Variable** with `number`? → Use `number` directly, no complex type needed
-2. **Action I/O** with integer value, **Flow target** (`flow://`)? → Use `object` + `complex_data_type_name: "lightning__numberType"`
-3. **Action I/O** with integer value, **Apex target** (`apex://`)? → Use `object` + `complex_data_type_name: "lightning__integerType"`
-4. **Action input/output** with decimal value? → Use `object` + `complex_data_type_name: "lightning__doubleType"`
-5. **Variable** with any other primitive? → Use the type directly (`string`, `boolean`, `date`)
-6. **Action I/O** with non-primitive? → Use `object` + appropriate `complex_data_type_name` from table below
-
-> **Key insight:** Bare `number` works in **variable declarations** but **fails at publish** in action inputs/outputs. This is the #1 cause of publish-fix-republish cycles.
-
-> **CRITICAL: Target type matters!** The valid `complex_data_type_name` for integer values differs by target type:
-> - **Flow targets** (`flow://`): Use `lightning__numberType` (NOT `lightning__integerType`)
-> - **Apex targets** (`apex://`): Use `lightning__integerType` (NOT `lightning__numberType`)
-> Using the wrong one causes a publish validation error.
-
-## Full Mapping Table
-
-| Data Type | `complex_data_type_name` Value | Notes |
-|-----------|-------------------------------|-------|
-| `string` | *(none needed)* | Primitive type — works in both variables and action I/O |
-| `number` (variable only) | *(none needed)* | **Variables only** — do NOT use bare `number` in action I/O |
-| `boolean` | *(none needed)* | Primitive type |
-| `object` (SObject) | `lightning__recordInfoType` | Use for Account, Contact, etc. |
-| `list[string]` | `lightning__textType` | Collection of text values |
-| `list[object]` | `lightning__textType` | Serialized as JSON text |
-| Apex Inner Class | `@apexClassType/NamespacedClass__InnerClass` | Namespace required |
-| Custom LWC Type | `lightning__c__CustomTypeName` | Custom component types |
-| Currency field | `lightning__currencyType` | For monetary values |
-| `datetime` | `lightning__dateTimeStringType` | DateTime values |
-| `integer` | `lightning__integerType` | Integer numbers (action I/O only) |
-| `double` / `number` | `lightning__doubleType` | Decimal/floating-point numbers (action I/O only) |
-| `object` (structured) | `lightning__objectType` | Complex data structures (action I/O only) |
-| `list` (generic) | `lightning__listType` | Arrays/lists (action I/O only) |
-
-> **Naming variance**: Upstream documentation uses `lightning__dateTimeType` while testing confirms `lightning__dateTimeStringType`. Both may be valid depending on API version — use `lightning__dateTimeStringType` as the tested default.
-
-## Agent Script → Lightning Type Mapping
-
-> Use this when troubleshooting type errors between Agent Script action I/O and Apex/Flow targets.
-
-| Agent Script Type | Lightning Type | Apex Type | Notes |
-|-------------------|---------------|-----------|-------|
-| `string` | `lightning__textType` | `String` | No `complex_data_type_name` needed |
-| `number` | `lightning__numberType` | `Decimal` / `Double` | No `complex_data_type_name` needed |
-| `boolean` | `lightning__booleanType` | `Boolean` | No `complex_data_type_name` needed |
-| `datetime` | `lightning__dateTimeStringType` | `DateTime` | **Actions only** — not valid for variables |
-| `date` | `lightning__dateType` | `Date` | Valid for both variables and actions |
-| `currency` | `lightning__currencyType` | `Decimal` | Annotated with currency type |
-
-**Pro Tip**: Don't manually edit `complex_data_type_name` - use the UI dropdown in **Agentforce Assets > Action Definition**, then export/import the action definition.

package/skills/developing-agentforce/references/deploy-reference.md

@@ -1,134 +0,0 @@
-# Deploy -- Bundle Publication Reference
-
-> Extracted from SKILL.md Section 18. This file is loaded on demand when deployment details are needed.
-
-## Overview
-
-Full deployment lifecycle for Agentforce agents: validate, deploy metadata, publish bundle, and activate.
-
-## Usage
-
-```bash
-# Validate + publish
-sf agent publish authoring-bundle --json --api-name MyAgent -o <org-alias>
-
-# Activate after publish
-sf agent activate --json --api-name MyAgent -o <org-alias>
-```
-
-## Deployment Phases
-
-### Phase 0: Safety Gate (Required)
-Read the `.agent` file and run safety review (see `safety-review-reference.md`). If any BLOCK finding exists, STOP deployment. WARN findings must be reported and acknowledged by the user before proceeding.
-
-### Phase 1: Pre-Deployment Validation
-```bash
-sf agent validate authoring-bundle --json --api-name MyAgent -o <org-alias>
-```
-
-### Phase 1b: Target Dependency Check
-Verify all flow/apex targets exist in the org before publishing. If missing, scaffold and deploy them first.
-
-### Phase 2: Deploy Supporting Metadata
-```bash
-sf project deploy start --json --source-dir force-app -o <org-alias>
-```
-
-### Phase 3: Publish Agent Bundle
-```bash
-sf agent publish authoring-bundle --json --api-name MyAgent -o <org-alias>
-```
-4-step process: Validate (~1-2s) -> Publish (~8-10s) -> Retrieve (~5-7s) -> Deploy (~4-6s)
-
-### Phase 4: Activate Agent
-```bash
-sf agent activate --json --api-name MyAgent -o <org-alias>
-```
-Note: `sf agent activate` may not support `--json` in all CLI versions. If it returns plain text, check for "successfully activated" in the output.
-
-Publishing creates an **inactive** version. Without activation, preview fails with "No valid version available".
-
-## Deploy vs Publish
-
-| What changes | `sf project deploy start` | `sf agent publish authoring-bundle` |
-|---|---|---|
-| Bundle metadata | Yes | Yes |
-| `system: instructions:` | Yes (via activate) | Yes |
-| `reasoning: actions:` (transitions + invocations) | **NO** | Yes |
-
-**Always prefer `sf agent publish authoring-bundle`.** If you change `reasoning: actions:`, publish is required.
-
-## Common Errors
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `Required fields missing: [BundleType]` | Extra fields in bundle-meta.xml | Use minimal: only `<bundleType>AGENT</bundleType>` |
-| `Internal Error, try again later` | Invalid default_agent_user or new agent platform bug | Query Einstein Agent Users; for new agents, create shell in Setup UI first |
-| `Duplicate value found: GenAiPluginDefinition` | `start_agent` and `subagent` share name | Use different names |
-| `Flow not found` | Metadata not deployed | Deploy flows before publishing |
-| `SetupEntityType is not supported for DML` | PermissionSet via Apex DML | Use Metadata API (`sf project deploy start`) |
-
-## Rollback
-
-```bash
-sf agent deactivate --json --api-name MyAgent -o <org>
-sf data query --json --query "SELECT Id, VersionNumber FROM BotVersion WHERE BotDefinition.DeveloperName = 'MyAgent' ORDER BY VersionNumber DESC LIMIT 2" -o <org>
-sf agent activate --json --api-name MyAgent --version-number <previous> -o <org>
-```
-
-## CI/CD Integration
-
-```yaml
-name: Deploy Agentforce Agent
-on:
-  push:
-    branches: [main]
-    paths: ['force-app/**']
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Install SF CLI
-        run: npm install -g @salesforce/cli
-      - name: Auth
-        run: |
-          echo "${{ secrets.SFDX_AUTH_URL }}" > auth.txt
-          sf org login sfdx-url --sfdx-url-file auth.txt --alias production
-      - name: Validate
-        run: sf agent validate authoring-bundle --json --api-name ${{ vars.AGENT_NAME }} -o production
-      - name: Deploy Metadata
-        run: sf project deploy start --json --source-dir force-app -o production
-      - name: Publish
-        run: sf agent publish authoring-bundle --json --api-name ${{ vars.AGENT_NAME }} -o production
-      - name: Activate
-        if: github.ref == 'refs/heads/main'
-        run: sf agent activate --json --api-name ${{ vars.AGENT_NAME }} -o production
-```
-
-## Pre-Deployment Checklist
-
-- [ ] All action targets exist in org (run discover first)
-- [ ] Agent Script validated (no syntax errors)
-- [ ] Einstein Agent User configured correctly
-- [ ] Supporting metadata deployed
-- [ ] Previous version backed up
-- [ ] Rollback plan documented
-
-## Post-Deployment Testing
-
-```bash
-sf agent preview start --json --use-live-actions --authoring-bundle MyAgent -o <org>
-# Read sessionId from the JSON response, then:
-sf agent preview send --json --authoring-bundle MyAgent --session-id <SESSION_ID> -u "Hello, I need help" -o <org>
-sf agent preview end --json --authoring-bundle MyAgent --session-id <SESSION_ID> -o <org>
-```
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Validation/deployment failed |
-| 2 | Critical failure |

package/skills/developing-agentforce/references/discover-reference.md

@@ -1,102 +0,0 @@
-# Discover -- Target Discovery Reference
-
-> Extracted from SKILL.md Section 16. This file is loaded on demand when target discovery details are needed.
-
-## Overview
-
-Validates that Agent Script `.agent` file targets actually exist in a Salesforce org, providing fuzzy suggestions for missing targets.
-
-## Usage
-
-```bash
-# List all active autolaunched flows (candidate action targets)
-sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+DeveloperName,ProcessType+FROM+Flow+WHERE+IsActive=true+AND+ProcessType='AutoLaunchedFlow'" -o <org-alias>
-
-# List all @InvocableMethod Apex classes
-sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+Name+FROM+ApexClass+WHERE+Body+LIKE+'%25InvocableMethod%25'" -o <org-alias>
-```
-
-## What it does
-
-### 1. Target Extraction
-- Finds all `.agent` files in the project
-- Parses each file to extract action `target:` values
-- Identifies target types: `flow://`, `apex://`, `retriever://`, `externalService://`, `generatePromptResponse://`
-
-### 2. Org Validation
-
-| Target Type | SOQL Query | Object Checked |
-|-------------|------------|----------------|
-| `flow://FlowName` | `SELECT ApiName FROM FlowDefinitionView WHERE ApiName = 'FlowName' AND IsActive = true` | Active flows only |
-| `apex://ClassName` | `SELECT Name FROM ApexClass WHERE Name = 'ClassName'` | Apex classes |
-| `retriever://RetrieverName` | `SELECT DeveloperName FROM DataKnowledgeSpace WHERE DeveloperName = 'RetrieverName'` | Data Cloud retrievers |
-| `externalService://ServiceName` | `SELECT DeveloperName FROM ExternalServiceRegistration WHERE DeveloperName = 'ServiceName'` | External services |
-| `generatePromptResponse://TemplateName` | `SELECT DeveloperName FROM PromptTemplate WHERE DeveloperName = 'TemplateName' AND Status = 'Active'` | Active prompt templates |
-
-### 3. Fuzzy Matching
-When a target is missing:
-- Queries for similar names using SOQL `LIKE` patterns
-- Calculates Levenshtein distance for close matches
-- Suggests up to 3 alternatives sorted by similarity
-
-### 4. I/O Parameter Validation (--validate-io)
-- **Flows:** Queries `/services/data/v63.0/actions/custom/flow/{FlowApiName}` for actual I/O schema
-- **Apex:** Checks `@InvocableVariable` field names match expected inputs/outputs
-- Results appear as non-blocking warnings
-
-### 5. Classification for Scaffold Pipeline
-
-| Signal in Description | Classification | Scaffold Output |
-|----------------------|---------------|-----------------|
-| "API", "HTTP", "REST", "external", URL | `callout` | Apex with Http + Remote Site + Custom Metadata |
-| SObject names, "query", "record", "SOQL" | `soql` | Apex with SOQL query logic |
-| No special signals | `basic` | Standard placeholder Apex |
-
-## Output Format
-
-```
-Agentforce ADLC Discovery Report
-
-Agent: OrderManagement
-  Subagent: order_inquiry
-    Action: get_order_status
-      Target: flow://Get_Order_Status         Found
-    Action: track_shipment
-      Target: flow://Track_Shipment_Flow      MISSING
-        Suggestions:
-          - Track_Shipping_Flow (distance: 2)
-
-Summary: 2/3 targets found (66.7%)
-```
-
-## Next Steps
-
-- Missing targets: Run scaffold to generate stubs (see `scaffold-reference.md`)
-- All found: Deploy (`sf agent publish authoring-bundle --json --api-name <AgentName> -o <org-alias>`)
-
-## Error Handling
-
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| `No .agent files found` | Wrong directory | Check `--agent-file` path |
-| `Invalid org alias` | Org not authenticated | Run `sf org login web --alias <org-alias>` |
-| `SOQL query failed` | Missing permissions | Ensure read access to Flow, ApexClass, etc. |
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | All targets found |
-| 1 | Some targets missing |
-| 2 | Critical failure |
-
-## Advanced (requires ADLC repo clone)
-
-The `discover.py` script provides automated discovery with fuzzy matching and I/O validation. It is NOT bundled with the skill — requires cloning the ADLC repo.
-
-```bash
-# From ADLC repo root:
-python3 scripts/discover.py -o <org-alias> --agent-file <path-to-agent-file>
-python3 scripts/discover.py -o <org-alias> --agent-dir force-app/main/default/aiAuthoringBundles
-python3 scripts/discover.py -o <org-alias> --agent-file MyAgent.agent --validate-io
-```