@salesforce/afv-skills 1.1.0 → 1.2.0

package/skills/agentforce-development/references/production-gotchas.md

@@ -0,0 +1,279 @@
+# Production Gotchas: Billing, Determinism & Performance
+Credit consumption, lifecycle hooks, determinism patterns, and performance guardrails in Agentforce.
+---
+
+## Credit Consumption Table
+
+| Operation | Credits | Notes |
+|-----------|---------|-------|
+| `@utils.transition` | FREE | Framework navigation |
+| `@utils.setVariables` | FREE | Framework state management |
+| `@utils.escalate` | FREE | Framework escalation |
+| `if`/`else` control flow | FREE | Deterministic resolution |
+| `before_reasoning` | FREE | Deterministic pre-processing (see note below) |
+| `after_reasoning` | FREE | Deterministic post-processing (see note below) |
+| `reasoning` (LLM turn) | FREE | LLM reasoning itself is not billed |
+| Prompt Templates | 2-16 | Per invocation (varies by complexity) |
+| Flow actions | 20 | Per action execution |
+| Apex actions | 20 | Per action execution |
+| Any other action | 20 | Per action execution |
+
+The `before_reasoning:` and `after_reasoning:` lifecycle hooks are validated. Content goes **directly** under the block (no `instructions:` wrapper). See "Lifecycle Hooks" section below for correct syntax.
+
+### Cost Optimization Pattern
+
+Fetch data once in `before_reasoning:`, cache in variables, reuse across topics.
+
+## Lifecycle Hooks
+
+```yaml
+topic main:
+   description: "Topic with lifecycle hooks"
+
+   # BEFORE: Runs deterministically BEFORE LLM sees instructions
+   before_reasoning:
+      # Content goes DIRECTLY here (NO instructions: wrapper!)
+      set @variables.pre_processed = True
+      set @variables.customer_tier = "gold"
+
+   # LLM reasoning phase
+   reasoning:
+      instructions: ->
+         | Customer tier: {!@variables.customer_tier}
+         | How can I help you today?
+
+   # AFTER: Runs deterministically AFTER LLM finishes reasoning
+   after_reasoning:
+      # Content goes DIRECTLY here (NO instructions: wrapper!)
+      set @variables.interaction_logged = True
+      if @variables.needs_audit == True:
+         set @variables.audit_flag = True
+```
+
+**Key Points:**
+- Content goes **directly** under `before_reasoning:` / `after_reasoning:` (NO `instructions:` wrapper)
+- Reliable primitives: `set`, `if`/`else`, `transition to`. `run` has inconsistent runtime behavior across bundle types — use it in `reasoning.actions:` or `instructions: ->` instead
+- `before_reasoning:` is FREE (no credit cost) - use for data prep
+- `after_reasoning:` is FREE (no credit cost) - use for logging, cleanup
+- `transition to` works in `after_reasoning:` — but if a topic transitions mid-reasoning, the original topic's `after_reasoning:` does NOT run
+
+**❌ WRONG Syntax (causes compile error):**
+```yaml
+before_reasoning:
+   instructions: ->      # ❌ NO! Don't wrap with instructions:
+      set @variables.x = True
+```
+
+**✅ CORRECT Syntax:**
+```yaml
+before_reasoning:
+   set @variables.x = True   # ✅ Direct content under the block
+```
+
+## Supervision vs Handoff
+
+| Term | Syntax | Behavior | Use When |
+|------|--------|----------|----------|
+| **Handoff** | `@utils.transition to @topic.X` | Control transfers completely, child generates final response | Checkout, escalation, terminal states |
+| **Supervision** | `@topic.X` (as action reference) | Parent orchestrates, child returns, parent synthesizes | Expert consultation, sub-tasks |
+
+```yaml
+# HANDOFF - child topic takes over completely:
+checkout: @utils.transition to @topic.order_checkout
+   description: "Proceed to checkout"
+# → @topic.order_checkout generates the user-facing response
+
+# SUPERVISION - parent remains in control:
+get_advice: @topic.product_expert
+   description: "Consult product expert"
+# → @topic.product_expert returns, parent topic synthesizes final response
+```
+
+**KNOWN BUG**: Adding ANY new action in Canvas view may inadvertently change Supervision references to Handoff transitions.
+
+## Action Output Flags for Zero-Hallucination Routing
+
+Control what the LLM can see and say.
+
+When defining actions in Agentforce Assets, use these output flags:
+
+| Flag | Effect | Use When |
+|------|--------|----------|
+| `filter_from_agent: True` | LLM **cannot** show this value to user | Preventing hallucinated responses (GA standard) |
+| `is_used_by_planner: True` | LLM **can** reason about this value | Decision-making, routing |
+
+**Zero-Hallucination Intent Classification Pattern:**
+```yaml
+# In Agentforce Assets - Action Definition outputs:
+outputs:
+   intent_classification: string
+      filter_from_agent: True     # LLM cannot show this to user (GA standard)
+      is_used_by_planner: True    # LLM can use for routing decisions
+
+# In Agent Script - LLM routes but cannot hallucinate:
+topic intent_router:
+   reasoning:
+      instructions: ->
+         run @actions.classify_intent
+         set @variables.intent = @outputs.intent_classification
+
+         if @variables.intent == "refund":
+            transition to @topic.refunds
+         if @variables.intent == "order_status":
+            transition to @topic.orders
+```
+
+## Action I/O Metadata Properties
+
+Complete reference for all metadata properties available on action definitions, inputs, and outputs.
+
+**Action-Level Properties:**
+
+| Property | Type | Effect |
+|----------|------|--------|
+| `label` | String | Display name in UI |
+| `description` | String | LLM reads this for decision-making |
+| `require_user_confirmation` | Boolean | Request user confirmation before execution (compiles; runtime no-op per Issue 6) |
+| `include_in_progress_indicator` | Boolean | Show spinner during execution |
+| `progress_indicator_message` | String | Custom spinner text |
+
+**Input Properties:**
+
+| Property | Type | Effect |
+|----------|------|--------|
+| `description` | String | Explains parameter to LLM |
+| `label` | String | Display name in UI |
+| `is_required` | Boolean | Marks input as mandatory for LLM |
+| `is_user_input` | Boolean | LLM extracts value from conversation |
+| `complex_data_type_name` | String | Lightning type mapping |
+
+**Output Properties:**
+
+| Property | Type | Effect |
+|----------|------|--------|
+| `description` | String | Explains output to LLM |
+| `label` | String | Display name in UI |
+| `filter_from_agent` | Boolean | `True` = hide from user display (GA standard) |
+| `is_displayable` | Boolean | `False` = hide from user (compile-valid alias) |
+| `is_used_by_planner` | Boolean | `True` = LLM can reason about value |
+| `developer_name` | String | Overrides the parameter's developer name |
+| `complex_data_type_name` | String | Lightning type mapping |
+
+`filter_from_agent: True` is the GA standard name. `is_displayable: False` is a compile-valid alias.
+
+### User Input Pattern
+
+With `is_user_input: True`:
+```yaml
+inputs:
+   customer_name: string
+      description: "Customer's full name"
+      is_user_input: True    # LLM pulls from what user already said
+      is_required: True      # Must have a value before action executes
+```
+
+## Action Chaining with `run` Keyword
+
+Parent action may complain about inputs needed by chained action - this is expected.
+
+```yaml
+process_order: @actions.create_order
+   with customer_id = @variables.customer_id
+   run @actions.send_confirmation        # Chains after create_order completes
+   set @variables.order_id = @outputs.id
+```
+
+KNOWN BUG: Chained actions with Prompt Templates don't properly map inputs using `Input:Query` format.
+
+For prompt template action definitions, input binding syntax, and grounded data patterns, see [references/action-prompt-templates.md](../references/action-prompt-templates.md).
+
+## Latch Variable Pattern for Topic Re-entry
+
+Topic selector doesn't properly re-evaluate after user provides missing input. Use a "latch" variable to force re-entry:
+
+```yaml
+variables:
+   verification_in_progress: mutable boolean = False
+
+start_agent topic_selector:
+   reasoning:
+      instructions: ->
+         if @variables.verification_in_progress == True:
+            transition to @topic.verification
+         | How can I help you today?
+      actions:
+         start_verify: @topic.verification
+            description: "Start identity verification"
+            set @variables.verification_in_progress = True
+
+topic verification:
+   reasoning:
+      instructions: ->
+         | Please provide your email to verify your identity.
+      actions:
+         verify: @actions.verify_identity
+            with email = ...
+            set @variables.verified = @outputs.success
+            set @variables.verification_in_progress = False
+```
+
+## Loop Protection Guardrail
+
+Agent Scripts have a built-in guardrail that limits iterations to approximately **3-4 loops** before breaking out and returning to the Topic Selector.
+
+**Best Practice**: Map out your execution paths and test for unintended circular references between topics.
+
+## Token & Size Limits
+
+| Limit Type | Value | Notes |
+|------------|-------|-------|
+| Max response size | 1,048,576 bytes (1MB) | Per agent response |
+| Plan trace limit (Frontend) | 1M characters | For debugging UI |
+| Transformed plan trace (Backend) | 32k tokens | Internal processing |
+| Active/Committed Agents per org | 100 max | Org limit |
+
+## Progress Indicators
+
+```yaml
+actions:
+   fetch_data: @actions.get_customer_data
+      description: "Fetch customer information"
+      include_in_progress_indicator: True
+      progress_indicator_message: "Fetching your account details..."
+```
+
+## VS Code Pull/Push NOT Supported
+
+```bash
+# ❌ ERROR when using source tracking:
+Failed to retrieve components using source tracking:
+[SfError [UnsupportedBundleTypeError]: Unsupported Bundle Type: AiAuthoringBundle
+
+# ✅ WORKAROUND - Use CLI directly:
+sf project retrieve start -m AiAuthoringBundle:MyAgent
+sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG
+```
+
+## Reserved `@InvocableVariable` Keywords
+
+Certain common words cannot be used as `@InvocableVariable` names in Apex classes called by Agent Script. Using them causes "SyntaxError: Unexpected '{keyword}'" during agent script compilation. (Validated March 2026)
+
+**Reserved names (cannot use as `@InvocableVariable`):**
+
+| Reserved Name | Workaround | Example |
+|---------------|------------|---------|
+| `model` | `vehicle_model`, `data_model`, `model_name` | `@InvocableVariable public String vehicle_model;` |
+| `description` | `issue_description`, `desc_text`, `description_field` | `@InvocableVariable public String issue_description;` |
+| `label` | `label_text`, `display_label`, `label_field` | `@InvocableVariable public String label_text;` |
+
+**How it manifests:**
+- Apex compiles and deploys successfully (these are valid Apex identifiers)
+- Error only appears when the Agent Script compiler processes the action's I/O schema
+- Error message: `SyntaxError: Unexpected 'model'` (or `description`, `label`)
+- Fix: Rename the `@InvocableVariable` in Apex, redeploy, then republish the agent
+
+## Language Block Quirks
+
+- Hebrew and Indonesian appear **twice** in the language dropdown
+- Selecting from the second set causes save errors
+- Use `adaptive_response_allowed: True` for automatic language adaptation

package/skills/agentforce-development/references/salesforce-cli-for-agents.md

@@ -0,0 +1,393 @@
+# Salesforce CLI for Agents Reference
+
+Command-by-command reference for Salesforce CLI `sf` commands covering agent generation, validation, preview, deployment, publishing, activationt/deactivation, testing, and Einstein Agent User setup.
+
+---
+
+## 1. Global Rules
+
+Always include `--json` as the FIRST flag after the base command. This ensures machine-readable output and prevents mid-tier LLMs from dropping the flag.
+
+```bash
+# CORRECT — --json first
+sf agent validate authoring-bundle --json --api-name Local_Info_Agent
+
+# WRONG — --json at the end or missing
+sf agent validate authoring-bundle --api-name Local_Info_Agent --json
+sf agent validate authoring-bundle --api-name Local_Info_Agent
+```
+
+Multiple metadata types in `--metadata` are space-separated arguments, NOT comma-separated. Wildcard patterns must be quoted.
+
+```bash
+# CORRECT
+sf project deploy start --json --metadata ApexClass Flow
+sf project retrieve start --json --metadata "AiAuthoringBundle:Local_Info_Agent_*"
+
+# WRONG
+sf project deploy start --json --metadata ApexClass,Flow
+sf project retrieve start --json --metadata AiAuthoringBundle:Local_Info_Agent_*
+```
+
+---
+
+## 2. Generate
+
+Create a new AiAuthoringBundle directory with boilerplate `.agent` and `.bundle-meta.xml` files.
+
+```bash
+sf agent generate authoring-bundle --json --no-spec --name "Agent Label" --api-name Agent_API_Name
+```
+
+- `--name`: Human-readable label (quoted if it contains spaces).
+- `--api-name`: Developer name. Must be a valid Salesforce API name (letters, numbers, underscores). This becomes the directory name under `aiAuthoringBundles/`.
+- `--no-spec`: Skip interactive agent spec generation. Always include this flag — the interactive spec generator cannot be used programmatically.
+
+The generated directory is placed at `<default_package_directory>/main/default/aiAuthoringBundles/<api-name>/`. Read `sfdx-project.json` to find the default package directory path.
+
+- `--force-overwrite`: Overwrites an existing bundle without interactive confirmation. DO NOT use unless intending to overwrite an existing authoring bundle.
+
+### Generated Output
+
+The generate command creates this structure:
+
+```
+force-app/main/default/aiAuthoringBundles/
+└── Agent_API_Name/
+    ├── Agent_API_Name.agent            # Agent Script file
+    └── Agent_API_Name.bundle-meta.xml  # Metadata XML
+```
+
+**Naming rules:** The folder name, `.agent` filename, and `.bundle-meta.xml` filename must always match `--api-name` exactly (case-sensitive).
+
+---
+
+## 3. Validate
+
+Check Agent Script for syntax errors, structural issues, and missing declarations. Always validate before deploying.
+
+```bash
+sf agent validate authoring-bundle --json --api-name Agent_API_Name
+```
+
+- `--api-name`: The AiAuthoringBundle directory name (same as `config.developer_name` in the `.agent` file).
+- Validates against local files only. Does not contact the org.
+
+---
+
+## 4. Deploy
+
+### Deploy Apex, Flow, or other backing logic
+
+```bash
+sf project deploy start --json --metadata ApexClass:ClassName
+```
+
+Deploy backing logic BEFORE deploying the AiAuthoringBundle. The bundle's action targets reference these components, and the platform validates they exist during bundle deploy.
+
+ALWAYS deploy each stub class IMMEDIATELY after customizing it. ALWAYS fix deploy errors BEFORE generating and deploying the next stub.
+
+### Deploy the AiAuthoringBundle
+
+```bash
+sf project deploy start --json --metadata AiAuthoringBundle:Agent_API_Name
+```
+
+This deploys ONLY the AiAuthoringBundle. A bare `sf project deploy start` (no `--metadata`) deploys ALL changed metadata in the project, which can inadvertently deploy agent metadata during routine development. Always scope deploys explicitly.
+
+### Safe routine deploy (non-agent metadata)
+
+```bash
+sf project deploy start --json --metadata ApexClass Flow
+```
+
+Explicitly list the metadata types to deploy. This avoids accidentally deploying AiAuthoringBundle changes.
+
+---
+
+## 5. Publish
+
+Convert a deployed AiAuthoringBundle into a running agent. Publishing creates the runtime entity graph (Bot, BotVersion, GenAiPlannerBundle) from the authoring bundle.
+
+```bash
+sf agent publish authoring-bundle --json --api-name Agent_API_Name
+```
+
+- `--api-name`: The AiAuthoringBundle directory name.
+- The agent must be deployed before it can be published.
+- The `default_agent_user` in the `.agent` file must exist in the target org and have the Einstein Agent license. An invalid user produces a misleading "Internal Error, try again later" message. See Section 12 for creation steps and [Agent User Setup & Permissions](agent-user-setup.md) for required permissions.
+- **Publishing does NOT activate.** Agents are published as `Inactive`. Tests, preview using `--api-name`, and access by end users continue using the previously active version until you explicitly run `sf agent activate`.
+
+---
+
+## 6. Activate and Deactivate
+
+Activation makes a published agent available for conversations and test execution.
+
+```bash
+sf agent activate --json --api-name Bot_API_Name
+```
+
+```bash
+sf agent deactivate --json --api-name Bot_API_Name
+```
+
+- `--api-name` here is the Bot API name (same as the agent's `config.developer_name`).
+- Only published agents can be activated. DRAFT-only agents cannot be activated.
+- Agent tests require an activated agent.
+
+---
+
+## 7. Retrieve
+
+### Retrieve the authoring bundle (editable source)
+
+```bash
+sf project retrieve start --json --metadata AiAuthoringBundle:Agent_API_Name
+```
+
+### Retrieve all version-suffixed snapshots (read-only)
+
+```bash
+sf project retrieve start --json --metadata "AiAuthoringBundle:Agent_API_Name_*"
+```
+
+Wildcard must be quoted. Version-suffixed bundles (e.g., `Local_Info_Agent_v1`) are immutable snapshots of published versions. They are read-only reference copies.
+
+### Retrieve the runtime entity graph
+
+```bash
+sf project retrieve start --json --metadata Agent:Agent_API_Name
+```
+
+The `Agent:` pseudo-type retrieves the runtime entities (Bot, BotVersion, GenAiPlannerBundle) created by publish. This does NOT include AiAuthoringBundle — use `AiAuthoringBundle:` for that.
+
+#### Caution! Metadata types are NOT sObjects
+
+`GenAiPlannerBundle`, `AiAuthoringBundle`, and `GenAiFunction` are **metadata types**. SOQL queries against them return `INVALID_TYPE`. Always use `sf project retrieve start --metadata` instead.
+
+```bash
+# WRONG — these are not sObjects
+sf data query --json -q "SELECT Id FROM GenAiPlannerBundle"
+sf data query --json -q "SELECT Id FROM AiAuthoringBundle"
+
+# CORRECT — use the Metadata API
+sf project retrieve start --json --metadata "GenAiPlannerBundle:AgentName"
+sf project retrieve start --json --metadata "AiAuthoringBundle:AgentName"
+```
+
+---
+
+## 8. Delete
+
+```bash
+sf project delete source --json --metadata AiAuthoringBundle:Agent_API_Name
+```
+
+- Deletes the AiAuthoringBundle from the org AND removes local source files.
+- Published agents cannot be fully deleted via CLI. The platform returns dependency errors. Use Salesforce Setup UI for published agent deletion.
+
+---
+
+## 9. Preview
+
+Preview runs the agent in a simulated or live environment for testing behavior before publishing.
+
+### Start a preview session
+
+```bash
+sf agent preview start --json --authoring-bundle Agent_API_Name
+```
+
+Returns a `sessionId` for subsequent send/end commands.
+
+### Send a message
+
+```bash
+sf agent preview send --json --authoring-bundle Agent_API_Name --session-id SESSION_ID -u "User message here"
+```
+
+- `--session-id`: From the `start` response.
+- `-u`: The user utterance (quoted).
+
+### End a preview session
+
+```bash
+sf agent preview end --json --authoring-bundle Agent_API_Name --session-id SESSION_ID
+```
+
+### Live preview (with real action execution)
+
+```bash
+sf agent preview start --json --authoring-bundle Agent_API_Name --use-live-actions
+```
+
+Add `--use-live-actions` to execute real backing logic instead of simulated responses. Live preview executes real Apex, Flows, and Prompt Templates in the org.
+
+### Anti-pattern: bare preview command
+
+```bash
+# WRONG — interactive REPL, hangs in automation
+sf agent preview --authoring-bundle Agent_API_Name
+
+# CORRECT — programmatic start/send/end
+sf agent preview start --json --authoring-bundle Agent_API_Name
+```
+
+The bare `sf agent preview` command is an interactive REPL designed for humans. It cannot be used programmatically because automation cannot send the ESC key to exit.
+
+### Anti-pattern: context variable injection in preview
+
+`sf agent preview` does NOT support context or session variable injection. There are no `--context`, `--session-var`, or `--variables` flags.
+
+---
+
+## 10. Test
+
+### Create a test from a spec
+
+```bash
+sf agent test create --json --spec specs/Agent_API_Name-testSpec.yaml --api-name Test_Definition_Name --force-overwrite
+```
+
+- `--spec`: Path to the local YAML test spec file.
+- `--api-name`: The name for the AiEvaluationDefinition in the org.
+- `--force-overwrite`: Prevents interactive mode if the AiEvaluationDefinition already exists. Always include this flag.
+- This command automatically deploys the AiEvaluationDefinition to the org. Use `--preview` to generate locally without deploying.
+
+### Run a test
+
+```bash
+sf agent test run --json --api-name Test_Definition_Name --wait 5
+```
+
+- `--api-name`: The AiEvaluationDefinition name (set by `--api-name` during `test create`). NOT the Bot name.
+- `--wait 5`: Synchronous execution with 5-minute timeout. Without `--wait`, returns a job ID immediately.
+- Tests run against activated published agents only.
+
+### Check test results (async fallback)
+
+```bash
+sf agent test results --json --job-id JOB_ID
+```
+
+Only needed if `--wait` was not used or timed out.
+
+### Generate a test spec from existing metadata
+
+```bash
+sf agent generate test-spec --from-definition path/to/AiEvaluationDefinition-meta.xml --output-file specs/Agent_API_Name-testSpec.yaml
+```
+
+Reverse-engineers a YAML test spec from an existing AiEvaluationDefinition. Do NOT use `sf agent generate test-spec` without `--from-definition` — the bare command is interactive and cannot be used programmatically.
+
+---
+
+## 11. Open in Browser
+
+These commands open Agentforce Studio in the user's default browser. Do NOT use `--json` with these commands — JSON mode outputs the target URL but does not open the browser.
+
+### View all authoring bundles
+
+```bash
+sf org open authoring-bundle
+```
+
+### View a specific published agent
+
+```bash
+sf org open agent --api-name Bot_API_Name
+```
+
+Only works for published agents. DRAFT-only bundles must be opened via `sf org open authoring-bundle`.
+
+---
+
+## 12. Einstein Agent User Setup
+
+**⚠️ This section applies only to `AgentforceServiceAgent`. Employee agents (`AgentforceEmployeeAgent`) must NOT have `default_agent_user` set.**
+
+### Check for an Existing Einstein Agent User
+
+```bash
+sf data query --json -q "SELECT Username, Name, IsActive FROM User WHERE Profile.UserLicense.Name = 'Einstein Agent' AND IsActive = true LIMIT 5"
+```
+
+If results are returned, confirm the correct username with the human before using it in the agent's config block.
+
+### Check Einstein Agent License Availability
+
+If no users are found, check whether the org has Einstein Agent licenses available:
+
+```bash
+sf data query --json -q "SELECT TotalLicenses, UsedLicenses FROM UserLicense WHERE Name = 'Einstein Agent'"
+```
+
+If `TotalLicenses` is 0, the org does not have the Einstein Agent add-on. **Stop and inform the human.**
+
+If `TotalLicenses > UsedLicenses`, a license is available and a new Einstein Agent User can be created.
+
+### Creating an Einstein Agent User
+
+#### Step 1: Query for the Einstein Agent User profile ID
+
+```bash
+sf data query --json -q "SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'"
+```
+
+#### Step 2: Create a User import JSON file (e.g., `data-import/User.json`)
+
+```json
+{
+    "records": [
+        {
+            "attributes": {
+                "type": "User",
+                "referenceId": "AgentUserRef1"
+            },
+            "ProfileId": "<PROFILE_ID_FROM_STEP_1>",
+            "Username": "<UNIQUE_USERNAME>",
+            "Alias": "AgntUsr",
+            "CommunityNickname": "Agent User<UNIQUE_STRING>",
+            "Email": "noreply@example.com",
+            "FirstName": "Agent",
+            "LastName": "User",
+            "IsActive": true,
+            "ForecastEnabled": false,
+            "EmailEncodingKey": "UTF-8",
+            "LanguageLocaleKey": "en_US",
+            "LocaleSidKey": "en_US",
+            "TimeZoneSidKey": "America/Los_Angeles"
+        }
+    ]
+}
+```
+
+#### Step 3: Import the user record
+
+```bash
+sf data import tree --json --files data-import/User.json
+```
+
+#### Step 4: Verify the user was created
+
+```bash
+sf data query --json -q "SELECT Username FROM User WHERE Profile.UserLicense.Name = 'Einstein Agent' AND IsActive = true LIMIT 5"
+```
+
+After creating the user, continue with permission setup in [Agent User Setup & Permissions](agent-user-setup.md).
+
+---
+
+## 13. CI/CD Pipeline
+
+The individual commands in this guide compose into a standard deployment pipeline:
+
+1. **Retrieve from Sandbox** — `sf project retrieve start --json --metadata AiAuthoringBundle:AgentName`
+2. **Validate Syntax** — `sf agent validate authoring-bundle --json --api-name AgentName`
+3. **Run Tests** — `sf agent test run --json --api-name TestDefName --wait 5`
+4. **Code Review** — Review `.agent` file changes in version control
+5. **Deploy to Production** — `sf project deploy start --json --metadata AiAuthoringBundle:AgentName`
+6. **Publish** — `sf agent publish authoring-bundle --json --api-name AgentName`
+7. **Activate** — `sf agent activate --json --api-name AgentName`
+8. **Verify Active Agent** — `sf agent preview start --json --api-name AgentName`

package/skills/agentforce-development/references/version-history.md

@@ -0,0 +1,23 @@
+# Version History
+
+Skill version changelog for agentforce-development.
+
+---
+
+## Current Skill (agentforce-development)
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 0.4.8 | 2026-03-17 | **Agent access guide + merge cleanup**: Adopted `agent-access-guide.md` from sf-permissions (import rules applied). Routed post-activation access step in Create and Deploy domains. Merged `preview-test-loop.md` content (jq trace diagnostics, fix strategies table, context variable limitations, utterance derivation) into `agent-validation-and-debugging.md`. Deleted orphaned `preview-test-loop.md`. Added custom object scanning guidance to Agent Spec creation. Refined post-action output field instructions. |
+| 0.4.7 | 2026-03-15 | **Post-action session state fix**: Added explicit post-action instructions to prevent session state corruption by specifying output fields the agent must reference. Driven by T02 run-2026-03-15-vc-02 finding. |
+| 0.4.6 | 2026-03-15 | **USER_MODE P0-1 fix**: Added static vs. dynamic SOQL guidelines to backing logic sections in `agent-design-and-spec-creation.md` and invocable Apex template. `AccessLevel.USER_MODE` required for dynamic SOQL. Added "Rules That Always Apply" cardinal rules block to SKILL.md (`--json` first, diagnose before fix, spec approval gate). |
+| 0.4.5 | 2026-03-15 | **Full editorial pass + spec approval gate**: Conciseness pass across all 9 SKILL.md domains. Added spec approval hard gate (user must approve Agent Spec before implementation). Added `filter_from_agent` output visibility to Agent Spec template. Restructured Agent Spec inputs/outputs sections. Step 8 redirect to Diagnose Behavioral Issues workflow. |
+| 0.4.4 | 2026-03-13 | **Staging + cleanup**: Moved unmerged reference files to `staging/` folder. Clarified live actions command syntax. Refined `agent-user-setup.md` license requirements and USER_MODE documentation. |
+| 0.4.3 | 2026-03-12 | **sf-skills merge: production-gotchas + new domain**: Added "Diagnose Production Issues" task domain to SKILL.md (9 domains total). Routed `production-gotchas.md` as primary reference. Added `production-gotchas.md` as secondary reference in Diagnose Compilation (reserved keywords trigger). Added `WITH USER_MODE` object permissions warning to `agent-user-setup.md` Section 6.2. Archived orphan `agent-user-setup-and-perms.md`. Fixed stale SKILL.md reference (Section 2 → Section 6.2). |
+| 0.4.2 | 2026-03-12 | **sf-skills merge: known-issues + one-at-a-time deploy**: Integrated `known-issues.md` into 6 of 8 SKILL.md domains with domain-specific loading triggers. Added one-at-a-time Apex stub deploy instruction to SKILL.md Create/Modify domains, `agent-design-and-spec-creation.md`, and `salesforce-cli-for-agents.md`. Moved Issue 16 (`connections:` → `connection messaging:`) to Resolved. |
+| 0.4.0 | 2026-03-11 | **T03 test run + type mapping restructure**: Restructured Section 5 type mapping in `agent-design-and-spec-creation.md` into Primitive + Complex tables keyed by `target` type. Added steps 10 (Activate) and 11 (Verify published agent) to Create, Modify, and Deploy domains. |
+| 0.3.2 | 2026-03-10 | **T02 post-fix run**: Platform-injected `show_command` tool diagnostic pattern added to `agent-validation-and-debugging.md`. Post-publish preview language strengthened in SKILL.md. |
+| 0.3.0 | 2026-03-10 | **T02 first run + test framework**: Created testing framework (README, run structure, scoring rubric). First T02 run: 13/13 SUCCESS. |
+| 0.2.0 | 2026-03-09 | **T01 first run**: Created T01 test scenario. First end-to-end test of skill. Identified `agent_type` inference gap. |
+| 0.1.0 | 2026-03-08 | **Initial skill**: SKILL.md router with 8 task domains. 7 reference files. Agent Spec template. Asset library. |
+