@salesforce/afv-skills 1.14.0 → 1.16.0

package/skills/creating-b2b-commerce-store/SKILL.md

@@ -2,7 +2,6 @@
 name: creating-b2b-commerce-store
 description: "Interactive workflow to create Commerce B2B Stores and retrieve storefront metadata. Use when users want to: create B2B Commerce stores, build Commerce storefronts, set up B2B stores from Vibes, retrieve Commerce metadata, deploy Commerce experiences, work with DigitalExperienceBundle for Commerce."
 Critical: "Agents must follow the interactive flow and NEVER create storefront metadata from scratch."
-license: Apache-2.0
 compatibility: "Requires Commerce licenses, Experience Cloud, Salesforce CLI"
 metadata:
   version: "1.0"

package/skills/debugging-apex-logs/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: debugging-apex-logs
 description: "Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use running-apex-tests), generating or fixing Apex code (use generating-apex), or Agentforce session tracing (use observing-agentforce)."
-license: MIT
 metadata:
   version: "1.1"
 ---

package/skills/deploying-metadata/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: deploying-metadata
 description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code (use generating-apex), building LWC components (use generating-lwc-components), creating metadata definitions (use generating-custom-object or generating-custom-field), or querying org data (use handling-sf-data)."
-license: MIT
 metadata:
   version: "1.1"
 ---

package/skills/deploying-omnistudio-datapacks/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: deploying-omnistudio-datapacks
 description: "Salesforce Industries DataPack deployment automation using Vlocity Build. TRIGGER when: user deploys or validates OmniStudio/Vlocity DataPacks with vlocity commands (packDeploy/packRetry/packExport/packGetDiffs), sets up DataPack CI/CD pipelines, or troubleshoots DataPack migration errors. DO NOT TRIGGER when: deploying Salesforce metadata with sf project deploy (use deploying-metadata), authoring OmniStudio artifacts (use building-omnistudio-*), or writing Apex/LWC business logic (use generating-apex/generating-lwc-components)."
-license: MIT
 metadata:
   version: "1.0"
 ---

package/skills/developing-agentforce/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: developing-agentforce
 description: "Build, modify, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, modifies, or asks about .agent files or aiAuthoringBundle metadata; changes agent behavior, responses, or conversation logic; designs agent actions, tools, subagents, or flow control; writes or reviews an Agent Spec; previews, debugs, deploys, publishes, or tests agents; uses Agent Script CLI commands (sf agent generate/preview/publish/test). DO NOT TRIGGER when: Apex development, Flow building, Prompt Template authoring, Experience Cloud configuration, or general Salesforce CLI tasks unrelated to Agent Script."
-license: Apache-2.0
 compatibility: "Requires Agentforce license, API v66.0+, Einstein Agent User"
 metadata:
   version: "1.0"

package/skills/fetching-salesforce-docs/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: fetching-salesforce-docs
 description: "Official Salesforce documentation retrieval skill. Use when you need authoritative Salesforce docs from developer.salesforce.com, help.salesforce.com, architect.salesforce.com, admin.salesforce.com, or lightningdesignsystem.com, especially when pages are JS-heavy, shell-rendered, or hard to extract with naive fetching. Use to ground answers in official Salesforce sources instead of third-party blogs or summaries. TRIGGER when: user asks for official Salesforce documentation, Apex or API reference, LWC docs, Agentforce docs, setup or help articles, or any doc from a Salesforce-owned domain. DO NOT TRIGGER when: user is asking for a code change, deployment task, or anything not requiring documentation retrieval — use the appropriate sf-* skill instead."
-license: MIT
 metadata:
   version: "1.1"
 ---

package/skills/generating-custom-lightning-type/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-custom-lightning-type
-description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work."
+description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, Custom Lightning Types (CLTs) with widget/mosaic/fragment rendition/renderer, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. When widget renditions are requested, you MUST first read the widget-rendition.md reference file in this skill's references/ directory and follow its complete workflow. This is complex - always use this skill for CLT work."
 metadata:
   version: "1.0"
 ---
@@ -12,6 +12,7 @@ Use this skill when you need to:
 - Generate JSON Schema-based type definitions for Lightning Platform
 - Configure CLTs for Einstein Agent actions
 - Set up editor and renderer configurations for custom UI
+- Create CLTs with widget/mosaic/fragment rendition
 - Troubleshoot deployment errors related to Custom Lightning Types
 
 ## Specification
@@ -28,6 +29,8 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - **Include editor/renderer config** only when you need custom UI behavior (custom LWC input/output components). Otherwise, omit.
 
 ## Critical Rules (Read First)
+- **CRITICAL: NEVER include the `"$schema"` field in schema.json**
+  - Salesforce CLT validator WILL REJECT schemas with this field, even if it's a valid JSON Schema `$schema` declaration.
 - **Root object schemas MUST include**:
   - `"type": "object"`
   - `"title"`
@@ -58,45 +61,15 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - **Object type validation**: the CLT root is validated to ensure `lightning:type` is exactly `lightning__objectType`.
 
 ## Primitive Types & Constraints
-- `lightning__textType`
-  - Max length 255
-- `lightning__multilineTextType`
-  - Max length 2000
-- `lightning__richTextType`
-  - Max length 100000
-- `lightning__urlType`
-  - Max length 2000
-  - Optional `lightning:allowedUrlSchemes` enum values: `https`, `http`, `relative`, `mailto`, `tel`
-- `lightning__dateType`
-  - Data pattern: YYYY-MM-DD
-- `lightning__timeType`
-  - Data pattern: HH:MM:SS.sssZ
-- `lightning__dateTimeType`
-  - Data shape is an object with required `dateTime` and optional `timeZone`
-- `lightning__numberType`
-  - Decimal numbers; optional `maximum`, `minimum`, `multipleOf`
-- `lightning__integerType`
-  - Whole numbers only; optional `maximum`, `minimum`
-- `lightning__booleanType`
-  - true/false
 
-## Allowed Property-Level Keywords
-When strict validation is enabled (`unevaluatedProperties: false`), keep each property minimal and prefer only keywords known to be allowed:
-- `title`, `description`, `einstein:description`
-- `type` (when used, ensure it matches the chosen `lightning:type`)
-- `lightning:type`
-- `maximum`, `minimum`, `multipleOf` (numeric)
-- `maxLength`, `minLength` (string)
-- `const`, `enum`
-- `lightning:textIndexed`, `lightning:supportsPersonalization`, `lightning:localizable`
-- `lightning:uiOptions`, `lightning:allowedUrlSchemes`
-- `lightning:tags` (metaschema restricts values; currently `flow` is the only known allowed tag)
+When you need the full list of supported primitive `lightning:type` identifiers, their constraints, and the allowed property-level keywords, read `assets/primitive-types-and-constraints.md` in this skill's directory.
 
 ## Generation Workflow
 1. **Confirm the CLT approach**
    - If referencing Apex: capture the exact class reference (`@apexClassType/namespace__ClassName$InnerClass`).
    - If using standard primitives: list the fields, their Lightning primitive types, and which fields are required.
 2. **Draft `schema.json`**
+   - **DO NOT include `"$schema"` at the top**
    - Start with the root object structure (required root fields).
    - Add `properties` using valid primitive `lightning:type` identifiers.
    - For nested-object properties, use **CLT Reference pattern**:
@@ -127,7 +100,7 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
    - **Avoid known-invalid patterns**:
      - Do not use `es_property_editors/inputList`.
      - Do not use `itemSchema` attributes.
-4. **(Optional) Draft `renderer.json`** (only if custom UI is required)
+4. **(Optional) Draft `renderer.json`** (only if custom UI or mosaic rendition is required)
    - **Supported shape:** Top-level `renderer` object with `renderer.componentOverrides` and `renderer.layout`.
      - Top-level `renderer` object.
      - Use `renderer.componentOverrides` for component overrides.
@@ -138,6 +111,15 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
      - Use `{!$attrs.<name>}` in attribute mappings when binding schema data to custom renderer component attributes.
      - **CRITICAL**: Attribute mappings like `{!$attrs.propertyName}` must reference properties that **actually exist** in your type schema. Referencing non-existent properties will fail validation.
      - **Type matching**: Attribute values must match the expected type for the component. For example, if a component expects a string attribute, passing an integer will fail validation.
+   - **Widget renderer pattern** (for widget rendition):
+       - **When to use:** Use this when users request "mosaic", "widget", "fragment", or "cross-platform rendering" for their CLT.
+       - **Structure:** `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }`
+       - **REQUIRED workflow:**
+           - **STOP**: Do NOT attempt to create the widget renderer yourself.
+           - **MANDATORY FIRST STEP**: You MUST fetch the reference file `references/widget-rendition.md` located in this skill's directory before proceeding.
+           - Follow the complete workflow documented in `widget-rendition.md` using the generated CLT schema as the grounding schema.
+           - The `widget-rendition.md` reference contains the full widget generation workflow: discovering UEM blocks via discoverUiComponents, calling getUiComponentSchemas, building the UEM tree, and writing renderer.json.
+           - **Do not** attempt to generate widget rendition without first fetching the `widget-rendition.md` reference file.
    - **Property-level override pattern**:
      - `renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }`. **Valid renderer components** (examples): `es_property_editors/outputText`, `es_property_editors/outputNumber`, `es_property_editors/outputImage`. Avoid input-style components in the renderer.
    - **Layout pattern for renderer**:
@@ -166,11 +148,6 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
          </targets>
      </LightningComponentBundle>
      ```
-7. **Deploy and validate**
-   - Run a final schema sanity check before deploy: valid `lightning:type` names, required fields present, and no disallowed keywords.
-   - Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles.
-   - Validate incrementally: if deployment fails, remove disallowed keywords first (especially `examples`, `items`, nested `lightning:type`).
-
 ## Common Deployment Errors
 | Error / Symptom | Likely Cause | Fix |
 |---|---|---|
@@ -200,3 +177,4 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 - [ ] Layout configurations use `lightning/propertyLayout` with ONLY the `property` attribute (no `label`, `title`, or other attributes)
 - [ ] All attribute mappings (`{!$attrs.propertyName}`) reference properties that exist in the type schema
 - [ ] Custom LWC components have correct targets in `-meta.xml`: `lightning__AgentforceInput` for editors, `lightning__AgentforceOutput` for renderers
+- [ ] Root schema does NOT include `"$schema"` field

package/skills/generating-custom-lightning-type/assets/primitive-types-and-constraints.md

@@ -0,0 +1,41 @@
+# Primitive Types & Constraints
+
+Reference for all supported Lightning primitive types and their allowed constraints. Read this when authoring property-level `lightning:type` identifiers or determining which keywords are valid on a given property.
+
+## Supported Types
+
+- `lightning__textType`
+  - Max length 255
+- `lightning__multilineTextType`
+  - Max length 2000
+- `lightning__richTextType`
+  - Max length 100000
+- `lightning__urlType`
+  - Max length 2000
+  - Optional `lightning:allowedUrlSchemes` enum values: `https`, `http`, `relative`, `mailto`, `tel`
+- `lightning__dateType`
+  - Data pattern: YYYY-MM-DD
+- `lightning__timeType`
+  - Data pattern: HH:MM:SS.sssZ
+- `lightning__dateTimeType`
+  - Data shape is an object with required `dateTime` and optional `timeZone`
+- `lightning__numberType`
+  - Decimal numbers; optional `maximum`, `minimum`, `multipleOf`
+- `lightning__integerType`
+  - Whole numbers only; optional `maximum`, `minimum`
+- `lightning__booleanType`
+  - true/false
+
+## Allowed Property-Level Keywords
+
+When strict validation is enabled (`unevaluatedProperties: false`), keep each property minimal and prefer only keywords known to be allowed:
+
+- `title`, `description`, `einstein:description`
+- `type` (when used, ensure it matches the chosen `lightning:type`)
+- `lightning:type`
+- `maximum`, `minimum`, `multipleOf` (numeric)
+- `maxLength`, `minLength` (string)
+- `const`, `enum`
+- `lightning:textIndexed`, `lightning:supportsPersonalization`, `lightning:localizable`
+- `lightning:uiOptions`, `lightning:allowedUrlSchemes`
+- `lightning:tags` (metaschema restricts values; currently `flow` is the only known allowed tag)

package/skills/generating-custom-lightning-type/references/widget-rendition.md

@@ -0,0 +1,124 @@
+# Widget Generation Guide
+
+## 📋 Overview
+Widgets are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating mosaic renditions for CLTs.
+
+## 🎯 Purpose
+Widgets render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc.
+
+## Schema Grounding
+Widget generation is **always schema-grounded** using a CLT's schema. The schema describes the data shape the widget should render. Extract property names, types, required vs optional, and nesting from the schema; then follow the full **Workflow** below, using this extracted structure to guide every step. Do not add or remove properties relative to the schema.
+
+## ⚙️ Composition
+A widget is a UEM (Unified Experience Model) tree of blocks and regions. The widget you return must follow the Typescript interfaces below:
+
+```ts
+interface BlockType {
+   type: 'block'
+   definition: string  // {namespace}/{blockName}
+   attributes?: Record<string, any>
+   children?: (BlockType | RegionType)[]
+}
+
+interface RegionType {
+   type: 'region'
+   name: string
+   children: BlockType[]
+}
+```
+---
+
+## 🔧 Available Metadata Actions
+
+### When to Use Each Action
+
+#### discoverUiComponents
+
+**Purpose:** Discover the palette of available blocks that can be used in widget composition.
+
+**Use for:** Finding available blocks before building your widget structure.
+
+**Input Parameters:**
+- `actionName` (**required***): "discoverUiComponents"
+- `metadataType` (**required**): "FRAGMENT"
+- `parameters` (**required**): JSON object with the below fields
+  - `pageType` (**required**): "FRAGMENT"
+  - `pageContext` (optional): JSON object - not required for FRAGMENT type
+  - `searchQuery` (optional): String to filter components by name or description
+
+**Returns:** List of components with:
+- `definition`: Fully qualified name (e.g., "namespace/definiton")
+- `description`: Component description
+- `label`: Human-readable label
+- `attributes`: Optional attribute metadata
+
+#### getUiComponentSchemas
+
+**Purpose:** Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules.
+
+**Use for:** You know which components you want but need to understand their properties before adding them to your widget.
+
+**Input Parameters:**
+- `actionName` (**required***): "getUiComponentSchemas"
+- `metadataType` (**required**): "FRAGMENT"
+- `parameters` (**required**): JSON object with the below fields
+  - `pageType` (**required**): "FRAGMENT"
+  - `componentDefinitions` (**required**): List of fully qualified names (e.g., ["namespace/definition"])
+    - **CRITICAL**: NEVER include "tile/mosaic" in this list. "tile/mosaic" is a container component used in renderer.json structure and **should not** be passed to getUiComponentSchemas
+  - `pageContext` (optional): JSON object - not required for FRAGMENT type
+  - `includeKnowledge` (optional): Boolean, defaults to true - includes additional component-specific guidance
+
+**Returns:**
+- `componentSchemas`: List of results (supports partial failures)
+- **Success entries**: Contains JSON schema with property definitions, types, constraints
+- **Failure entries**: Contains error message explaining why schema couldn't be retrieved
+- `$defs`: Schema definitions and references (if schema transformation applied)
+
+**Key Feature:** Supports partial failures - if some components can't be found, you still get schemas for the successful ones.
+
+---
+
+## Attribute binding using placeholder syntax
+
+- **Where to use:** When block properties must display or pass runtime data from the grounding schema, use the **Placeholder Syntax** below so that the runtime binds values into the widget. Check each block's schema (from `getUiComponentSchemas`) for the correct property name (e.g. `value`, `text`, `label`).
+- **Placeholder Syntax:** Use `{!$attrs.<attrName>}` as the placeholder for each block property that should receive data.
+  `<attrName>` **must** match the property name from the grounding schema so that the runtime can resolve its value.
+  Example: for a schema property `title`, set the block property to `{!$attrs.title}`.
+- **List / iterative data:** Only the children (list items) hold bound values; the parent list block does not. For each item inside a list (e.g. `tile/listItem`), use `{!$attrs.<listAttrName>.item}` so the runtime binds the current item. `<listAttrName>` MUST match the schema property name of the list. Example: for `icons`, use `"{!$attrs.icons.item}"` on the list item.
+
+---
+
+## 💡Workflow
+
+1. **Schema Parsing**
+- Parse the schema and extract: property names, types, required vs optional, and nested structure. Use this as the **widget spec**.
+
+2. **Discover Available Blocks** (**REQUIRED** - do NOT skip)
+- Use **discoverUiComponents metadata action** above to explore what blocks are available.
+- Use property types from the **widget spec** to inform `searchQuery` (e.g. text → "text", number → "number").
+
+3. **Select Components**
+- Choose blocks that can represent each property in the **widget spec** from the results of step 2.
+
+4. **Get Component Schemas** (**REQUIRED** - do NOT skip)
+- Use **getUiComponentSchemas metadata action** with the selected block definitions from step 3 and review block properties' metadata.
+
+5. **Build Widget**
+- Construct the UEM tree. Map each property in the **widget spec** to block properties and preserve order of the **widget spec**.
+- For block properties that must show or pass runtime data, use the placeholder syntax (see **Attribute binding using placeholder syntax** above).
+- Use block properties from the schemas retrieved in step 4.
+
+6. **Write output to CLT Bundle**
+- Always write to `lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` (or the correct target subfolder for the product surface, e.g. `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/` when applicable).
+  Check **required root override pattern** below -
+  `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ ... ] — array of UEM nodes - contains the widget UEM generated using the **Workflow** steps 1-5 above }`
+
+---
+
+## ⚠️ Important Notes
+
+- **widget spec** includes both required and optional attributes - review carefully to ensure valid configuration.
+- When using **`execute_metadata_action`** tool, always supply **`parameters`** with the required fields above; missing `parameters` or required keys causes hard failures, not partial results.
+- Block definitions always follow the `{namespace}/{blockName}` convention.
+- Use the same definition format returned by `discoverUiComponents` when calling `getUiComponentSchemas`
+- Placeholder syntax for non-list properties is `{!$attrs.<attrName>}` and for list properties is `{!$attrs.<listAttrName>.item}`.

package/skills/generating-lwc-components/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: generating-lwc-components
 description: "Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc/**/*.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use generating-apex), Aura components, or Visualforce."
-license: MIT
 metadata:
   version: "1.1"
 ---

package/skills/generating-mermaid-diagrams/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: generating-mermaid-diagrams
 description: "Salesforce architecture diagrams using Mermaid with ASCII fallback. Use this skill when generating text-based diagrams for Salesforce architecture, OAuth flows, ERDs, integration sequences, or Agentforce structure. TRIGGER when: user says \"diagram\", \"visualize\", \"ERD\", or asks for sequence diagrams, flowcharts, class diagrams, or architecture visualizations in Mermaid. DO NOT TRIGGER when: user wants PNG/SVG image output (use generating-visual-diagrams), or asks about non-Salesforce systems."
-license: MIT
 compatibility: "Requires Mermaid-capable renderer for diagram previews"
 metadata:
   version: "1.0"

package/skills/generating-visual-diagrams/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: generating-visual-diagrams
 description: "AI-powered image generation for Salesforce visuals via Nano Banana Pro. Use this skill when the user needs rendered PNG/SVG output such as visual ERDs (Entity Relationship Diagrams), UI mockups, wireframes, or architecture illustrations. TRIGGER when: user asks for PNG/SVG output, UI mockups, wireframes, visual ERDs, or says \"generate image\" / \"create mockup\". DO NOT TRIGGER when: text-based Mermaid diagrams (use generating-mermaid-diagrams), or non-visual documentation tasks."
-license: MIT
 metadata:
   version: "1.0"
 ---

package/skills/handling-sf-data/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: handling-sf-data
 description: "Salesforce data operations with 130-point scoring. Use this skill to create, update, delete, bulk import/export, generate test data, and clean up org records using sf CLI and anonymous Apex. TRIGGER when: user creates test data, performs bulk import/export, uses sf data CLI commands, needs data factory patterns for Apex tests, or needs to seed/clean records in a Salesforce org. DO NOT TRIGGER when: SOQL query writing only (use querying-soql), Apex test execution (use running-apex-tests), or metadata deployment (use deploying-metadata)."
-license: MIT
 metadata:
   version: "1.1"
 ---

package/skills/harmonizing-datacloud/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: harmonizing-datacloud
 description: "Salesforce Data Cloud Harmonize phase. Use this skill when the user works with DMOs, mappings, relationships, identity resolution, unified profiles, data graphs, or universal IDs. TRIGGER when: user works with DMOs, mappings, relationships, identity resolution, unified profiles, data graphs, or universal IDs. DO NOT TRIGGER when: the task is only about streams/DLOs (use preparing-datacloud), segments/insights (use segmenting-datacloud), retrieval/search (use retrieving-datacloud), or STDM/session tracing (use observing-agentforce)."
-license: MIT
 compatibility: "Requires an external community sf data360 CLI plugin and a Data Cloud-enabled org"
 metadata:
   version: "1.0"

package/skills/integrating-b2b-commerce-open-code-components/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: integrating-b2b-commerce-open-code-components
 description: "Integrate Salesforce B2B Commerce open source components from GitHub into B2B Commerce stores. Use when users mention \"integrate open code components\", \"open source B2B commerce\", \"add open code components\", \"forcedotcom/b2b-commerce-open-source-components\", or want to add open source commerce components to their store. Copies all components and labels so they become available in Experience Builder."
-license: LICENSE.txt has complete terms
 allowed-tools: Bash(git clone:*) Bash(cp:*) Read
 metadata:
   version: "1.0"

package/skills/investigating-agentforce-architecture/README.md

@@ -0,0 +1,156 @@
+# investigating-agentforce-architecture
+
+Declared architecture snapshot for a single Agentforce agent: planner + topics + actions + flows + Apex + prompts + NGA plugins. Reads design-time metadata only (`BotDefinition` + `GenAi*` Tooling objects + Metadata API retrieve) — no runtime audit data.
+
+Input: an `agent_api_name` (the `BotDefinition.DeveloperName`) and an org alias. Optional `agent_version_api_name` to pin a version; otherwise the active `BotVersion` resolves.
+
+Output: two files under `~/.vibe/data/investigating-agentforce-architecture/<org_id15>/<agent>__<version>/` — a normalized `<agent>_<ver>_metadata_tree.json` and a human-readable `<agent>_<ver>_architecture.md`. Override with `--data-dir <path>` (other runtimes pass this to land artifacts under their own distribution layout).
+
+---
+
+## Runtime budget
+
+**30–45s typical, ≤60s hard cap** on the reference fixtures.
+
+A naive sequential implementation (Metadata API retrieves only) would take 90–220s. Speedup: **3–5×**.
+
+Scaling note: large bots with many flows scale approximately linearly in flow count. Each Flow metadata retrieve is an individual SOQL round-trip; a 20-flow bot takes proportionally longer than a 5-flow bot. The 7 planner-side Tooling SOQL fan-outs are constant-cost (single fan-out regardless of bot size); the flow/apex body fetch wave scales with ref count.
+
+---
+
+## Prerequisites
+
+| Tool | Why |
+|---|---|
+| `sf` CLI (authenticated against the target org) | Shells `sf org display --target-org <alias> --json` for access token, and `sf sobject describe` for the 7-day channel probe |
+| Python 3.10+ | `pathlib`, dataclasses, `\|` union types, `concurrent.futures` |
+
+---
+
+## Usage
+
+Invoked conversationally through whatever skill-aware runtime hosts it. Example prompts:
+
+| User says | Skill does |
+|---|---|
+| `document the architecture of MyAgent in my-org-alias` | Resolve active version, fetch tree, render architecture.md + Mermaid |
+| `draw the invocation graph for MySalesAgent v5 in my-org-alias-3` | Same, pinned to v5 |
+| `what tools does MyAgent2 have in my-org-alias-2` | Fetch tree, surface the plugin/function inventory from the rendered architecture.md |
+| `re-fetch the architecture of MyAgent — I think metadata changed` | Pass `--force` to bypass the cache |
+
+See `SKILL.md` for the full flag table and sample prompts.
+
+---
+
+## Directory layout
+
+```
+investigating-agentforce-architecture/
+├── SKILL.md                       Skill contract (inputs, outputs, pipeline, invariants)
+├── README.md                      This file
+├── assets/
+│   ├── soql/*.soql                Tooling + Data SOQL templates
+│   ├── cli/*.yaml                 sf CLI recipes (subprocess invocation specs)
+│   └── mermaid/*.mmd              Mermaid templates for the invocation graph
+├── references/
+│   ├── soql_fields.md             Per-sObject field reference (13 sObjects)
+│   ├── architecture_sections.md   Section-by-section structure of the rendered architecture.md
+│   └── contract.json              metadata_tree.json schema contract
+├── scripts/
+│   ├── _shared/                   Path helpers + fs_guard validators + sql escapers
+│   ├── main.py                    Orchestrator entry point
+│   ├── config.py                  Shared paths, cache TTLs, validated path builders
+│   ├── soql_loader.py             Template loader with fs_guard-validated substitution
+│   ├── sf_cli.py                  sf CLI subprocess wrapper (yaml.safe_load + stderr redaction)
+│   ├── rest_client.py             urllib wrapper (Authorization-stripping redirect handler)
+│   ├── resolve_bot.py             BotDefinition + BotVersion + planner name lookup
+│   ├── retrieve_planner.py        Metadata retrieve for GenAiPlannerBundle + NGA plugins
+│   ├── parallel_retrieve.py       7-channel parallel Tooling SOQL fan-out
+│   ├── parse_bundle.py            XML → normalized node shapes
+│   ├── parse_wave.py              BFS expansion of flow/apex/prompt refs
+│   ├── probe_channels.py          7-day-TTL channel describe probe
+│   ├── cache_check.py             Asset-hash-aware cache freshness
+│   ├── finalize.py                Merge waves → metadata_tree.json
+│   ├── render_architecture.py     architecture.md + Mermaid graph
+│   ├── resolve_invocation_target.py  ID-prefix router for NGA InvocationTargets
+│   └── tests/                     Unit + integration tests (unittest)
+└── tools/
+    ├── emit_env.py                Env-var emit helper (Phase 0.5)
+    ├── emit_result.py             Final RESULT block renderer
+    ├── sanitize.py                Stdin → safe-string filter
+    └── write_emit_ctx.py          Per-phase ctx writer
+```
+
+---
+
+## Architecture
+
+### Channel strategy — SOQL-first
+
+```
+Seed query: planner_definition_by_agent_chain (chain-LIKE lookup → planner id)
+
+6 parallel Tooling SOQL channels (keyed on the resolved planner id):
+    - plugins_by_planner
+    - planner_bundle_functions (join)
+    - functions_by_plugins
+    - planner_attrs_by_parent_ids
+    - plugin_functions_by_plugin_ids (join)
+    - plugin_instructions_by_plugin_ids
+
++ Data API SOQL for Flow / Apex bodies (batched by id list)
++ Metadata retrieve ONLY for:
+    - GenAiPromptTemplate (prompt bodies)
+    - NGA external plugins (when planner is ConcurrentMultiAgentOrchestration etc.)
+```
+
+Most of the 3–5× speedup over a naive Metadata-API-only implementation comes from collapsing a sequential zip-retrieve chain into a single Tooling SOQL fan-out.
+
+### Planner normalization — classic ReAct vs NGA
+
+One tree shape, two planner families:
+
+| `PlannerType` examples | Family | InvocationTarget style |
+|---|---|---|
+| `ReactAiPlannerV1`, `SequentialPlannerIntentClassifier` | Classic ReAct | DeveloperName strings |
+| `ConcurrentMultiAgentOrchestration`, `AnthropicCompatibleV1` | NGA | Sometimes 15/18-char Ids (ID-prefix routed) |
+
+`resolve_invocation_target.py` routes NGA InvocationTargets by Salesforce ID prefix (`01p` → ApexClass, `301` → Flow, etc.). Unknown prefixes become `_unresolved[]` entries with `reason="unknown-id-prefix:<prefix>"` — never silently dropped.
+
+### Cache layers
+
+1. **Tree cache** — `metadata_tree.json` is reused unless `--force`. Cache key includes asset-hashes of every SOQL / YAML / Mermaid template shipped with the skill, so changing a template busts the cache automatically.
+2. **Channel probe cache** — 7-day TTL on `sf sobject describe` results for the 13 sObjects the skill touches. `--reprobe` forces a refresh (needed after Salesforce quarterly releases that rename / remove fields). Mandatory-field gate: a probe that sees any mandatory field missing (per `probe_channels.MANDATORY_FIELDS`) flips `status: PROBE_FAILED` so the caller surfaces a clean error.
+
+---
+
+## Key behaviors
+
+### Idempotence
+
+Re-running the same `(org, agent, version)` overwrites prior artifacts in place. Safe to run repeatedly during development.
+
+### Partial-results surfacing
+
+No silent drops. Any unresolved ref — unknown ID prefix, failed SOQL, missing describe field — lands in `_unresolved[]` with a `reason=...` string. Top-level `STATUS` is `OK` on a clean run, `PARTIAL_OK` when any channel degrades.
+
+### Cycle handling
+
+Per-branch ancestor-path cycle detection is the primary termination primitive: the same flow visited along its own ancestor chain emits `_cycle_back_to:<path>` instead of recursing. `MAX_BFS_DEPTH=20` is a defensive last-resort guard against pathological graphs that evade per-branch detection; real-world agents bottom out well before that.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `sf org display failed` | Re-authenticate: `sf org login web --alias <alias>` |
+| `INVALID_FIELD` from a SOQL asset | Salesforce renamed / removed the field in a quarterly release. Run with `--reprobe` to refresh the 7-day channel cache and pick up the new schema |
+| `STATUS=PROBE_FAILED` on first run | Channel probe saw a mandatory field missing. Check `channels.json` under the probe cache dir for which sObject / field — may require org-side feature enablement |
+| Tree for classic ReAct agent shows `_unresolved` entries for NGA plugins | Expected — the NGA external-plugin retrieve is skipped when the planner shape is classic. Those entries can be ignored |
+
+---
+
+## Author
+
+Raghul Jayagopal (RJ), Salesforce ANZ FDE.