@salesforce/afv-skills 1.20.0 → 1.22.0

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

@@ -0,0 +1,395 @@
+# 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.
+
+#### Not all agent metadata supports SOQL
+
+`BotDefinition` and `BotVersion` support SOQL — use `sf data query` to get agent record IDs, version status, or activation state.
+
+`GenAiPlannerBundle`, `AiAuthoringBundle`, and `GenAiFunction` do NOT support SOQL — queries return `INVALID_TYPE`. Use `sf project retrieve start --metadata` instead.
+
+```bash
+# SOQL-queryable — use sf data query
+sf data query --json -q "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName = 'Agent_API_Name'"
+sf data query --json -q "SELECT Id, VersionNumber, Status FROM BotVersion WHERE BotDefinition.DeveloperName = 'Agent_API_Name'"
+
+# NOT SOQL-queryable — use 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 --json --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-generate/references/scaffold-reference.md

@@ -0,0 +1,153 @@
+# Scaffold -- Stub Generation Reference
+
+> Extracted from SKILL.md Section 17. This file is loaded on demand when scaffold details are needed.
+
+## Overview
+
+Generates stub metadata files (Flow XML, Apex classes) for Agent Script targets that don't exist in the org, with SObject-aware field discovery when connected.
+
+## Usage
+
+Generate stub metadata files directly using the type mapping and action classification rules below. Parse the `.agent` file to extract action targets and their I/O schemas, then generate Flow XML or Apex classes as appropriate.
+
+For automated scaffold generation, see the [Advanced](#advanced-requires-adlc-repo-clone) section at the bottom.
+
+## What it does
+
+### 1. Discovery Phase (unless --all)
+- Runs discover to identify missing targets
+- Extracts I/O schemas from the `.agent` file
+- Maps Agent Script types to Salesforce types
+
+### 2. Flow Generation (`flow://` targets)
+Generates complete Flow XML with input/output variables, assignment placeholders, and start element.
+
+### 3. Apex Generation (`apex://` targets)
+Generates Apex class with `@InvocableMethod`, input/output wrapper classes, and test class with 75% coverage boilerplate.
+
+### 4. Action Classification
+
+| Signal | Classification | Generated Files |
+|--------|---------------|-----------------|
+| "API", "HTTP", "REST", URL | `callout` | Apex + `HttpCalloutMock` test + Remote Site + Custom Metadata |
+| "query", "record", "SOQL" | `soql` | Apex with SOQL logic + test |
+| No special signals | `basic` | Standard placeholder Apex + test |
+
+### 5. SObject-Aware Generation
+When connected to an org:
+- Queries SObject metadata for referenced types
+- Generates accurate SOQL queries in Apex stubs
+- Creates proper field mappings in Flow elements
+
+### 6. Type Mapping
+
+| Agent Script | Flow Type | Apex Type |
+|-------------|-----------|-----------|
+| `string` | `String` | `String` |
+| `number` | `Number` | `Decimal` |
+| `boolean` | `Boolean` | `Boolean` |
+| `date` | `Date` | `Date` |
+| `id` | `String` | `Id` |
+| `object` | `Apex` (SObject) | `SObject` |
+| `list[string]` | `String` (multipicklist) | `List<String>` |
+
+## Output Structure
+
+```
+force-app/main/default/
+  flows/
+    Get_Order_Status.flow-meta.xml
+  classes/
+    OrderProcessor.cls
+    OrderProcessor.cls-meta.xml
+    OrderProcessorTest.cls
+    OrderProcessorTest.cls-meta.xml
+  permissionsets/
+    Agent_Action_Access.permissionset-meta.xml
+```
+
+## Best Practices
+
+### Stub Data Quality (CRITICAL for Grounding)
+
+Scaffolded stubs MUST return **realistic-looking data**, not `'TODO'` or empty strings. When the platform LLM invokes an action and gets `'TODO'` back, it has no useful data to present — so it falls back to its training data (SMALL_TALK grounding) or fabricates results (hallucination).
+
+**Evidence:** Comcast eval stubs returned realistic comparison data → 93% grounding rate. JPMorgan eval stubs returned `'TODO'` → 40% grounding rate.
+
+| WRONG | CORRECT |
+|-------|---------|
+| `res.status = 'TODO';` | `res.status = 'Shipped - In Transit';` |
+| `res.summary = '';` | `res.summary = '23 cases open, 8 high-priority, avg resolution 2.3 days';` |
+| `res.result = 'TODO: implement';` | `res.result = '{"match_score": 0.92, "case_id": "500ABC"}';` |
+
+**Guidelines for realistic stub data:**
+- Use the action description and output field names to infer plausible values
+- Include the input values in the response (e.g., `'Order ' + req.order_id + ' is Shipped'`)
+- For JSON outputs, return a valid JSON string with all expected fields populated
+- For numeric outputs, return non-zero values that make business sense
+- For list outputs, return 2-3 sample items
+
+### I/O Variable Matching
+Scaffolded stubs MUST have I/O names that **exactly match** the `.agent` file. Case sensitivity matters: `order_id` != `Order_Id` != `orderId`.
+
+### Flow XML Element Ordering (CRITICAL)
+All elements of the same type MUST be grouped together. Interleaved elements cause Metadata API rejection.
+
+Recommended order: `apiVersion` -> `description` -> `label` -> `variables` -> `assignments` -> `decisions` -> `recordLookups` -> `recordCreates` -> `recordUpdates` -> `start` -> `status` -> `processType`
+
+### Post-Scaffolding Steps
+1. Review generated code (stubs have TODO comments)
+2. Add business logic
+3. Update test classes with meaningful assertions
+4. Add error handling and FLS/CRUD checks
+
+## Backing Logic Selection Criteria
+
+| Criteria | Choose Flow | Choose Apex |
+|----------|-------------|-------------|
+| Data operations | Simple CRUD, record lookups | Complex queries, bulk ops, cross-object logic |
+| External callouts | No callouts needed | REST/SOAP callouts, Named Credentials |
+| Business logic | Simple branching, assignments | Complex algorithms, string manipulation |
+| Existing assets | Flow already exists | Apex class already exists |
+| Maintenance | Admins maintain | Developers maintain |
+| Testing | Flow test coverage built-in | Requires Apex test class (75%+ coverage) |
+
+**Rule of thumb:** If the action does a single record lookup or update with no callouts, use Flow. If it involves callouts, complex logic, or bulk operations, use Apex. When in doubt, prefer Apex — it's more debuggable and less constrained.
+
+## Integration Workflow
+
+```bash
+# 1. Discover missing targets (CLI-native)
+sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+DeveloperName+FROM+Flow+WHERE+IsActive=true+AND+ProcessType='AutoLaunchedFlow'" -o myorg
+sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+Name+FROM+ApexClass+WHERE+Body+LIKE+'%25InvocableMethod%25'" -o myorg
+# 2. Generate stubs for missing targets (use type mapping + action classification above)
+# 3. Edit stubs with business logic
+# 4. Deploy to org
+sf project deploy start --json --source-dir force-app/main/default -o myorg
+# 5. Verify targets exist
+sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+DeveloperName+FROM+Flow+WHERE+IsActive=true+AND+ProcessType='AutoLaunchedFlow'" -o myorg
+# 6. Publish agent
+sf agent publish authoring-bundle --json --api-name MyAgent -o myorg
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All stubs generated |
+| 1 | Some stubs failed |
+| 2 | Critical failure |
+
+## Advanced (requires ADLC repo clone)
+
+The `scaffold.py` script automates stub generation with SObject-aware field discovery. It is NOT bundled with the skill — requires cloning the ADLC repo.
+
+```bash
+# From ADLC repo root — scaffold missing targets (runs discover first)
+python3 scripts/scaffold.py \
+  --agent-file path/to/Agent.agent -o <org-alias> --output-dir force-app/main/default
+
+# Scaffold all targets without checking org
+python3 scripts/scaffold.py \
+  --agent-file path/to/Agent.agent --all --output-dir force-app/main/default
+```

package/skills/agentforce-generate/references/scoring-rubric.md

@@ -0,0 +1,24 @@
+# 100-Point Scoring Rubric
+
+> Extracted from SKILL.md Section 6. This file is loaded on demand when the scoring rubric is needed.
+
+Score every generated agent against this rubric before presenting to the user.
+
+| Category | Points | Key Criteria |
+|----------|--------|--------------|
+| Structure & Syntax | 15 | All required blocks present (`system`, `config`, `start_agent`, at least one `subagent`). Correct block order (`system` → `config` → `variables` → ...). Proper nesting. Consistent 4-space indentation. Valid field names. All string values double-quoted. |
+| Safety & Responsible AI | 15 | Evaluated via safety review (7 categories): AI disclosure present, no impersonation/deception/manipulation, responsible data handling, no harmful content (including euphemisms), no discrimination (direct or proxy), clear scope boundaries, escalation paths for sensitive topics. Deduct 15 for any BLOCK finding, 5 per WARN finding. |
+| Deterministic Logic | 20 | `after_reasoning` patterns for post-action routing. FSM transitions with no dead-end subagents. `available when` guards for security-sensitive actions. Post-action checks at TOP of `instructions: ->`. |
+| Instruction Resolution | 20 | Clear, actionable instructions. Procedural mode (`->`) where conditionals are needed. Literal mode (`\|`) where static text suffices. Variable injection where dynamic. Conditional instructions based on state. |
+| FSM Architecture | 10 | Hub-and-spoke or verification gate pattern. Every subagent reachable. Every subagent has an exit (transition or escalation). No orphan subagents. Start subagent routes correctly. |
+| Action Configuration | 10 | Proper Level 1 definitions with targets and I/O schemas. Correct Level 2 invocations with `with`/`set`. Slot-filling (`...`) for conversational inputs. Output capture into variables. Correct type mapping for action I/O (use `object` + `complex_data_type_name` for SObjects and custom Lightning types). |
+| Deployment Readiness | 10 | Valid `default_agent_user`. `developer_name` matches folder. `bundle-meta.xml` present with `<bundleType>AGENT</bundleType>`. Linked variables for service agents (`EndUserId`, `RoutableId`, `ContactId`). |
+
+## Score Interpretation
+
+| Score | Meaning | Action |
+|-------|---------|--------|
+| 90-100 | Production-ready | Deploy with confidence |
+| 75-89 | Good with minor issues | Fix noted items, then deploy |
+| 60-74 | Needs work | Address structural issues before deploy |
+| Below 60 | BLOCK | Major rework required |

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

@@ -0,0 +1,23 @@
+# Version History
+
+Skill version changelog for agentforce-generate.
+
+---
+
+## Current Skill (agentforce-generate)
+
+| 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. |
+