@salesforce/afv-skills 1.8.0 → 1.9.1

package/skills/analyzing-omnistudio-dependencies/references/namespace-guide.md

@@ -0,0 +1,300 @@
+<!-- Parent: analyzing-omnistudio-dependencies/SKILL.md -->
+
+# OmniStudio Namespace Reference Guide
+
+## Overview
+
+Salesforce OmniStudio exists under three distinct namespaces depending on the org's industry package and migration status. Every OmniStudio operation must target the correct namespace — queries, metadata retrieval, and deployment all use namespace-specific object and field API names.
+
+| Namespace | Package Context | Typical Orgs |
+|-----------|----------------|--------------|
+| **Core** (no prefix) | Industries / OmniStudio managed package migrated to Core | Orgs on API 234.0+ (Spring '22+) that have completed the Core migration |
+| **vlocity_cmt** | Vlocity Communications, Media & Energy | Telco, media, energy & utilities industry orgs |
+| **vlocity_ins** | Vlocity Insurance & Health | Insurance, health, and life sciences industry orgs |
+
+---
+
+## Detection Algorithm
+
+### Step-by-Step Probing
+
+Run SOQL queries against each namespace's primary object. The first query that succeeds determines the namespace.
+
+```
+1. Probe Core:
+   SELECT COUNT() FROM OmniProcess
+   → Success? Namespace = Core. Stop.
+   → Failure (INVALID_TYPE)? Continue.
+
+2. Probe vlocity_cmt:
+   SELECT COUNT() FROM vlocity_cmt__OmniScript__c
+   → Success? Namespace = vlocity_cmt. Stop.
+   → Failure (INVALID_TYPE)? Continue.
+
+3. Probe vlocity_ins:
+   SELECT COUNT() FROM vlocity_ins__OmniScript__c
+   → Success? Namespace = vlocity_ins. Stop.
+   → Failure (INVALID_TYPE)? OmniStudio not installed.
+```
+
+### CLI Implementation
+
+```bash
+# Core probe
+sf data query --query "SELECT COUNT() FROM OmniProcess" --target-org myorg --json 2>/dev/null
+# Check: result.totalSize >= 0 means Core namespace
+
+# vlocity_cmt probe
+sf data query --query "SELECT COUNT() FROM vlocity_cmt__OmniScript__c" --target-org myorg --json 2>/dev/null
+
+# vlocity_ins probe
+sf data query --query "SELECT COUNT() FROM vlocity_ins__OmniScript__c" --target-org myorg --json 2>/dev/null
+```
+
+### Interpreting Results
+
+- **Exit code 0 + JSON with `totalSize`**: Namespace is present
+- **Exit code non-zero or `INVALID_TYPE` error**: Namespace not installed
+- **Exit code 0 + `totalSize: 0`**: Namespace exists but no components created yet (still valid)
+
+---
+
+## Object Mapping
+
+### Primary Container Objects
+
+These objects store OmniScript, Integration Procedure, FlexCard, and Data Mapper definitions.
+
+| Concept | Core | vlocity_cmt | vlocity_ins |
+|---------|------|-------------|-------------|
+| OmniScript / Integration Procedure | `OmniProcess` | `vlocity_cmt__OmniScript__c` | `vlocity_ins__OmniScript__c` |
+| OmniScript / IP Elements | `OmniProcessElement` | `vlocity_cmt__Element__c` | `vlocity_ins__Element__c` |
+| FlexCard | `OmniUiCard` | `vlocity_cmt__VlocityUITemplate__c` | `vlocity_ins__VlocityUITemplate__c` |
+| Data Mapper (DataRaptor) | `OmniDataTransform` | `vlocity_cmt__DRBundle__c` | `vlocity_ins__DRBundle__c` |
+| Data Mapper Item | `OmniDataTransformItem` | `vlocity_cmt__DRMapItem__c` | `vlocity_ins__DRMapItem__c` |
+| Calculation Matrix | `CalculationMatrix` | `vlocity_cmt__CalculationMatrix__c` | `vlocity_ins__CalculationMatrix__c` |
+| Calculation Procedure | `CalculationProcedure` | `vlocity_cmt__CalculationProcedure__c` | `vlocity_ins__CalculationProcedure__c` |
+
+### Relationship Fields (Element → Parent)
+
+| Concept | Core | vlocity_cmt | vlocity_ins |
+|---------|------|-------------|-------------|
+| Element → Process lookup | `OmniProcessId` | `vlocity_cmt__OmniScriptId__c` | `vlocity_ins__OmniScriptId__c` |
+| DM Item → DM lookup | `OmniDataTransformId` | `vlocity_cmt__DRBundleId__c` | `vlocity_ins__DRBundleId__c` |
+
+---
+
+## Field Mapping
+
+### OmniProcess / OmniScript Fields
+
+| Concept | Core (OmniProcess) | vlocity_cmt (OmniScript__c) | vlocity_ins (OmniScript__c) |
+|---------|-------------------|---------------------------|---------------------------|
+| Type | `Type` | `vlocity_cmt__Type__c` | `vlocity_ins__Type__c` |
+| SubType | `SubType` | `vlocity_cmt__SubType__c` | `vlocity_ins__SubType__c` |
+| Language | `Language` | `vlocity_cmt__Language__c` | `vlocity_ins__Language__c` |
+| Is Active | `IsActive` | `vlocity_cmt__IsActive__c` | `vlocity_ins__IsActive__c` |
+| Version | `VersionNumber` | `vlocity_cmt__Version__c` | `vlocity_ins__Version__c` |
+| Type Category | `TypeCategory` | N/A (use `vlocity_cmt__IsIntegrationProcedure__c`) | N/A (use `vlocity_ins__IsIntegrationProcedure__c`) |
+| Custom HTML | `CustomHtmlTemplates` | `vlocity_cmt__CustomHtmlTemplates__c` | `vlocity_ins__CustomHtmlTemplates__c` |
+| Is Reusable | `IsReusable` | `vlocity_cmt__IsReusable__c` | `vlocity_ins__IsReusable__c` |
+| Procedure Key | N/A | `vlocity_cmt__ProcedureKey__c` | `vlocity_ins__ProcedureKey__c` |
+
+**Note on TypeCategory vs IsIntegrationProcedure**: In Core namespace, `TypeCategory` distinguishes OmniScripts from Integration Procedures (`'OmniScript'` vs `'IntegrationProcedure'`). In Vlocity namespaces, use the boolean field `IsIntegrationProcedure__c` instead.
+
+### Element Fields
+
+| Concept | Core (OmniProcessElement) | vlocity_cmt (Element__c) | vlocity_ins (Element__c) |
+|---------|--------------------------|-------------------------|-------------------------|
+| Name | `Name` | `Name` | `Name` |
+| Type | `Type` | `vlocity_cmt__Type__c` | `vlocity_ins__Type__c` |
+| Property Set Config | `PropertySetConfig` | `vlocity_cmt__PropertySet__c` | `vlocity_ins__PropertySet__c` |
+| Order | `SequenceNumber` | `vlocity_cmt__Order__c` | `vlocity_ins__Order__c` |
+| Is Active | `IsActive` | `vlocity_cmt__Active__c` | `vlocity_ins__Active__c` |
+| Parent Element | `ParentElementId` | `vlocity_cmt__ParentElementId__c` | `vlocity_ins__ParentElementId__c` |
+| Level | `Level` | `vlocity_cmt__Level__c` | `vlocity_ins__Level__c` |
+
+### FlexCard / UI Template Fields
+
+| Concept | Core (OmniUiCard) | vlocity_cmt (VlocityUITemplate__c) | vlocity_ins (VlocityUITemplate__c) |
+|---------|-------------------|-----------------------------------|-----------------------------------|
+| Name | `Name` | `Name` | `Name` |
+| Is Active | `IsActive` | `vlocity_cmt__IsActive__c` | `vlocity_ins__IsActive__c` |
+| Definition | `Definition` | `vlocity_cmt__Definition__c` | `vlocity_ins__Definition__c` |
+| Author Name | `AuthorName` | `vlocity_cmt__Author__c` | `vlocity_ins__Author__c` |
+| Version | `VersionNumber` | `vlocity_cmt__Version__c` | `vlocity_ins__Version__c` |
+| Template Type | N/A | `vlocity_cmt__TemplateType__c` | `vlocity_ins__TemplateType__c` |
+
+### Data Mapper / DataRaptor Fields
+
+| Concept | Core (OmniDataTransform) | vlocity_cmt (DRBundle__c) | vlocity_ins (DRBundle__c) |
+|---------|-------------------------|--------------------------|--------------------------|
+| Name | `Name` | `Name` | `Name` |
+| Type | `Type` | `vlocity_cmt__Type__c` | `vlocity_ins__Type__c` |
+| Is Active | `IsActive` | `vlocity_cmt__IsActive__c` | `vlocity_ins__IsActive__c` |
+| Input Type | `InputType` | `vlocity_cmt__InputType__c` | `vlocity_ins__InputType__c` |
+| Output Type | `OutputType` | `vlocity_cmt__OutputType__c` | `vlocity_ins__OutputType__c` |
+
+### Data Mapper Item Fields
+
+| Concept | Core (OmniDataTransformItem) | vlocity_cmt (DRMapItem__c) | vlocity_ins (DRMapItem__c) |
+|---------|------------------------------|---------------------------|---------------------------|
+| Input Object | `InputObjectName` | `vlocity_cmt__InterfaceObject__c` | `vlocity_ins__InterfaceObject__c` |
+| Output Object | `OutputObjectName` | `vlocity_cmt__TargetFieldObjectType__c` | `vlocity_ins__TargetFieldObjectType__c` |
+| Input Field | `InputFieldName` | `vlocity_cmt__InterfaceFieldAPIName__c` | `vlocity_ins__InterfaceFieldAPIName__c` |
+| Output Field | `OutputFieldName` | `vlocity_cmt__TargetFieldAPIName__c` | `vlocity_ins__TargetFieldAPIName__c` |
+| Filter Data Type | `FilterDataType` | `vlocity_cmt__FilterDataType__c` | `vlocity_ins__FilterDataType__c` |
+| Query Sequence | `InputObjectQuerySequence` | `vlocity_cmt__InterfaceObjectLookupOrder__c` | `vlocity_ins__InterfaceObjectLookupOrder__c` |
+
+---
+
+## Metadata Type Names for Deployment
+
+When using `sf project retrieve start` or `sf project deploy start`, reference the correct metadata type:
+
+| Component | Core Metadata Type | Vlocity Metadata Type |
+|-----------|-------------------|----------------------|
+| OmniScript | `OmniScript` | N/A (use Vlocity Build Tool) |
+| Integration Procedure | `OmniIntegrationProcedure` | N/A (use Vlocity Build Tool) |
+| FlexCard | `OmniUiCard` | N/A (use Vlocity Build Tool) |
+| Data Mapper | `OmniDataTransform` | N/A (use Vlocity Build Tool) |
+| Data Mapper Item | `OmniDataTransformItem` | N/A (use Vlocity Build Tool) |
+
+**Note**: Only Core namespace components support standard Salesforce metadata API deployment. Vlocity namespace components require the Vlocity Build Tool (`vlocity_build`) for migration between orgs.
+
+### Retrieve Example (Core)
+```bash
+sf project retrieve start --metadata OmniScript --target-org myorg
+sf project retrieve start --metadata OmniDataTransform --target-org myorg
+```
+
+---
+
+## Mixed Namespace Scenarios
+
+### During Core Migration
+
+Organizations migrating from a Vlocity namespace to Core may temporarily have components under both namespaces. During this transition:
+
+1. **Probe both namespaces** — if both return results, the org is mid-migration
+2. **Core components take precedence** — runtime uses Core namespace objects when both exist
+3. **Report the state** — alert the user that migration is in progress and both namespaces contain data
+4. **Do not modify Vlocity-namespace components** — they are frozen during migration
+
+### Detection of Mixed State
+
+```bash
+# Check if Core has components
+sf data query --query "SELECT COUNT() FROM OmniProcess" --target-org myorg --json 2>/dev/null
+
+# Also check if Vlocity still has components
+sf data query --query "SELECT COUNT() FROM vlocity_cmt__OmniScript__c" --target-org myorg --json 2>/dev/null
+```
+
+If both return `totalSize > 0`, the org is in a mixed namespace state.
+
+### Recommended Actions During Mixed State
+
+- Inventory components under both namespaces
+- Compare counts to assess migration progress
+- Flag components that exist only in the old namespace (not yet migrated)
+- Do not create components under the old namespace
+
+---
+
+## Data Mapper Type Values
+
+The `Type` field on OmniDataTransform / DRBundle indicates the mapper's purpose:
+
+| Type Value | Description |
+|-----------|-------------|
+| `Extract` | Reads data from Salesforce objects |
+| `Transform` | Maps and transforms data between structures |
+| `Load` | Writes data to Salesforce objects |
+| `Turbo Extract` | High-performance read (bypasses sharing rules) |
+
+---
+
+## SOQL Query Templates
+
+### Core Namespace — Full Inventory
+
+```soql
+-- All OmniScripts
+SELECT Id, Type, SubType, Language, IsActive, VersionNumber, LastModifiedDate
+FROM OmniProcess
+WHERE TypeCategory = 'OmniScript'
+ORDER BY Type, SubType, Language, VersionNumber DESC
+
+-- All Integration Procedures
+SELECT Id, Type, SubType, Language, IsActive, VersionNumber, LastModifiedDate
+FROM OmniProcess
+WHERE TypeCategory = 'IntegrationProcedure'
+ORDER BY Type, SubType, Language, VersionNumber DESC
+
+-- All FlexCards
+SELECT Id, Name, IsActive, AuthorName, VersionNumber, LastModifiedDate
+FROM OmniUiCard
+ORDER BY Name, VersionNumber DESC
+
+-- All Data Mappers
+SELECT Id, Name, Type, IsActive, InputType, OutputType, LastModifiedDate
+FROM OmniDataTransform
+ORDER BY Name
+```
+
+### vlocity_cmt Namespace — Full Inventory
+
+```soql
+-- All OmniScripts
+SELECT Id, vlocity_cmt__Type__c, vlocity_cmt__SubType__c,
+       vlocity_cmt__Language__c, vlocity_cmt__IsActive__c, vlocity_cmt__Version__c
+FROM vlocity_cmt__OmniScript__c
+WHERE vlocity_cmt__IsIntegrationProcedure__c = false
+ORDER BY vlocity_cmt__Type__c, vlocity_cmt__SubType__c
+
+-- All Integration Procedures
+SELECT Id, vlocity_cmt__Type__c, vlocity_cmt__SubType__c,
+       vlocity_cmt__Language__c, vlocity_cmt__IsActive__c, vlocity_cmt__Version__c
+FROM vlocity_cmt__OmniScript__c
+WHERE vlocity_cmt__IsIntegrationProcedure__c = true
+ORDER BY vlocity_cmt__Type__c, vlocity_cmt__SubType__c
+
+-- All FlexCards / UI Templates
+SELECT Id, Name, vlocity_cmt__IsActive__c, vlocity_cmt__Version__c
+FROM vlocity_cmt__VlocityUITemplate__c
+ORDER BY Name
+
+-- All Data Mappers (DataRaptors)
+SELECT Id, Name, vlocity_cmt__Type__c, vlocity_cmt__IsActive__c
+FROM vlocity_cmt__DRBundle__c
+ORDER BY Name
+```
+
+### vlocity_ins Namespace — Full Inventory
+
+```soql
+-- All OmniScripts
+SELECT Id, vlocity_ins__Type__c, vlocity_ins__SubType__c,
+       vlocity_ins__Language__c, vlocity_ins__IsActive__c, vlocity_ins__Version__c
+FROM vlocity_ins__OmniScript__c
+WHERE vlocity_ins__IsIntegrationProcedure__c = false
+ORDER BY vlocity_ins__Type__c, vlocity_ins__SubType__c
+
+-- All Integration Procedures
+SELECT Id, vlocity_ins__Type__c, vlocity_ins__SubType__c,
+       vlocity_ins__Language__c, vlocity_ins__IsActive__c, vlocity_ins__Version__c
+FROM vlocity_ins__OmniScript__c
+WHERE vlocity_ins__IsIntegrationProcedure__c = true
+ORDER BY vlocity_ins__Type__c, vlocity_ins__SubType__c
+
+-- All FlexCards / UI Templates
+SELECT Id, Name, vlocity_ins__IsActive__c, vlocity_ins__Version__c
+FROM vlocity_ins__VlocityUITemplate__c
+ORDER BY Name
+
+-- All Data Mappers (DataRaptors)
+SELECT Id, Name, vlocity_ins__Type__c, vlocity_ins__IsActive__c
+FROM vlocity_ins__DRBundle__c
+ORDER BY Name
+```

package/skills/building-omnistudio-callable-apex/CREDITS.md

@@ -0,0 +1,9 @@
+# Credits
+
+This skill draws on established Salesforce Industries patterns for callable Apex implementations,
+including the `System.Callable` interface, `VlocityOpenInterface`, and `VlocityOpenInterface2`
+extension points used in OmniStudio and Industries integrations.
+
+The guidance, migration patterns, and bundled examples reflect best practices for secure,
+deterministic callable implementations across Industries extension points such as OmniScripts,
+Integration Procedures, and DataRaptors.

package/skills/building-omnistudio-callable-apex/README.md

@@ -0,0 +1,80 @@
+# building-omnistudio-callable-apex
+
+Generates and reviews Salesforce Industries Common Core (OmniStudio/Vlocity) Apex callable
+implementations. Build secure, deterministic `System.Callable` classes with a 120-point scoring
+rubric and migration guidance from legacy `VlocityOpenInterface` implementations.
+
+## Features
+
+- **Callable Generation**: Create `System.Callable` classes with safe action dispatch
+- **Callable Review**: Analyze existing callable implementations for risks and fixes
+- **120-Point Scoring**: Validation across 7 callable-specific categories
+- **VlocityOpenInterface / VlocityOpenInterface2 Support**: Phase 2 contract mapping and Phase 3 implementation patterns for `invokeMethod(String methodName, Map<String, Object> inputMap, Map<String, Object> outputMap, Map<String, Object> options)`
+- **Migration Guidance**: Patterns for moving from `VlocityOpenInterface`/`VlocityOpenInterface2` to `System.Callable`
+- **Testing Examples**: Test class patterns for actions, errors, and bulk inputs
+
+## Quick Start
+
+### 1. Invoke the skill
+
+```
+Skill: building-omnistudio-callable-apex
+Request: "Create a callable implementation for Order actions with createOrder and cancelOrder"
+```
+
+### 2. Answer requirements questions
+
+The skill will ask about:
+- Industries entry point (OmniScript, Integration Procedure, DataRaptor)
+- Action names (strings passed into `call`)
+- Input/output contract (required keys, response shape)
+- Data access needs and security expectations
+
+### 3. Review generated code
+
+The skill generates:
+- Callable class with explicit `switch on action`
+- Consistent response envelope
+- Test class examples for action coverage and error paths
+
+## Bundled Examples
+
+- [examples/Test_QuoteByProductCallable/](examples/Test_QuoteByProductCallable/) — read-only callable example with SOQL and test coverage
+- [examples/Test_VlocityOpenInterfaceConversion/](examples/Test_VlocityOpenInterfaceConversion/) — migration pattern from legacy `VlocityOpenInterface`
+- [examples/Test_VlocityOpenInterface2Conversion/](examples/Test_VlocityOpenInterface2Conversion/) — migration pattern from `VlocityOpenInterface2`
+
+## Scoring System (120 Points)
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Contract & Dispatch | 20 | Explicit actions, `switch on`, versioned strings |
+| Input Validation | 20 | Required keys, type coercion, null guards |
+| Security | 20 | CRUD/FLS checks, `with sharing`, stripInaccessible |
+| Error Handling | 15 | Typed exceptions, consistent errors |
+| Bulkification & Limits | 20 | No SOQL/DML in loops, list inputs |
+| Testing | 15 | Positive/negative/contract/bulk tests |
+| Documentation | 10 | ApexDoc for class and action methods |
+
+**Thresholds**: ✅ 90+ (Ready) | ⚠️ 70-89 (Review) | ❌ <70 (Block)
+
+## Cross-Skill Integration
+
+| Related Skill | When to Use |
+|---------------|-------------|
+| generating-apex | General Apex work beyond callable implementations |
+| generating-custom-object / generating-custom-field | Verify object/field availability before coding |
+| running-apex-tests | Run tests and analyze coverage |
+| deploying-metadata | Deploy callable classes to an org |
+
+## Documentation
+
+- [Skill Instructions](SKILL.md)
+
+### VlocityOpenInterface / VlocityOpenInterface2
+
+The skill includes design (Phase 2) and implementation (Phase 3) guidance for the Open Interface signature `invokeMethod(String methodName, Map<String, Object> inputMap, Map<String, Object> outputMap, Map<String, Object> options)`. Use this when extending legacy OmniStudio/Vlocity integration points or building dual Callable + Open Interface implementations.
+
+## Requirements
+
+- sf CLI v2
+- Target Salesforce org

package/skills/building-omnistudio-callable-apex/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: building-omnistudio-callable-apex
+description: "Salesforce Industries Common Core (OmniStudio/Vlocity) Apex callable generation and review skill with 120-point scoring. Use when creating, reviewing, or migrating Industries callable Apex implementations. TRIGGER when: user creates or reviews System.Callable classes, migrates VlocityOpenInterface or VlocityOpenInterface2, or builds Industries callable extensions used by OmniStudio, Integration Procedures, or DataRaptors. DO NOT TRIGGER when: generic Apex classes or triggers (use generating-apex), building Integration Procedures (use building-omnistudio-integration-procedure), authoring OmniScripts (use building-omnistudio-omniscript), configuring Data Mappers (use building-omnistudio-datamapper), or analyzing namespace/dependency issues (use analyzing-omnistudio-dependencies)."
+license: MIT
+metadata:
+  version: "1.0"
+---
+
+# building-omnistudio-callable-apex: Callable Apex for Salesforce Industries Common Core
+
+Specialist for Salesforce Industries Common Core callable Apex implementations. Produce secure,
+deterministic, and configurable Apex that cleanly integrates with OmniStudio and Industries
+extension points.
+
+## Scope
+
+- **In scope**: Creating `System.Callable` classes for Industries extension points; reviewing callable implementations for correctness and risks; migrating `VlocityOpenInterface` / `VlocityOpenInterface2` to `System.Callable`; 120-point scoring and validation
+- **Out of scope**: Generic Apex classes without callable interface (use `generating-apex`); building Integration Procedures (use `building-omnistudio-integration-procedure`); authoring OmniScripts (use `building-omnistudio-omniscript`); deploying Apex classes (use `deploying-metadata`)
+
+---
+
+## Core Responsibilities
+
+1. **Callable Generation**: Build `System.Callable` classes with safe action dispatch
+2. **Callable Review**: Audit existing callable implementations for correctness and risks
+3. **Validation & Scoring**: Evaluate against the 120-point rubric
+4. **Industries Fit**: Ensure compatibility with OmniStudio/Industries extension points
+
+---
+
+## Workflow (4-Phase Pattern)
+
+### Phase 1: Requirements Gathering
+
+Ask for:
+- Entry point (OmniScript, Integration Procedure, DataRaptor, or other Industries hook)
+- Action names (strings passed into `call`)
+- Input/output contract (required keys, types, and response shape)
+- Data access needs (objects/fields, CRUD/FLS (Create/Read/Update/Delete and Field-Level Security) rules)
+- Side effects (DML, callouts, async requirements)
+
+Then:
+1. Scan for existing callable classes: `Glob: **/*Callable*.cls`
+2. Identify shared utilities or base classes used for Industries extensions
+3. Create a task list
+
+---
+
+### Phase 2: Design & Contract Definition
+
+**Define the callable contract**:
+- Action list (explicit, versioned strings)
+- Input schema (required keys + types)
+- Output schema (consistent response envelope)
+
+**Recommended response envelope**:
+```
+{
+  "success": true|false,
+  "data": {...},
+  "errors": [ { "code": "...", "message": "..." } ]
+}
+```
+
+**Action dispatch rules**:
+- Use `switch on action`
+- Default case throws a typed exception
+- No dynamic method invocation or reflection
+
+**VlocityOpenInterface / VlocityOpenInterface2 contract mapping**:
+
+When designing for legacy Open Interface extensions (or dual Callable + Open Interface support), map the signature:
+
+```
+invokeMethod(String methodName, Map<String, Object> inputMap, Map<String, Object> outputMap, Map<String, Object> options)
+```
+
+| Parameter | Role | Callable equivalent |
+|-----------|------|---------------------|
+| `methodName` | Action selector (same semantics as `action`) | `action` in `call(action, args)` |
+| `inputMap` | Primary input data (required keys, types) | `args.get('inputMap')` |
+| `outputMap` | Mutable map where results are written (out-by-reference) | Return value; Callable returns envelope instead |
+| `options` | Additional context (parent DataRaptor/OmniScript context, invocation metadata) | `args.get('options')` |
+
+Design rules for Open Interface contracts:
+- Treat `inputMap` and `options` as the combined input schema
+- Define what keys must be written to `outputMap` per action (success and error cases)
+- Preserve `methodName` strings so they align with Callable `action` strings
+- Document whether `options` is required, optional, or unused for each action
+
+---
+
+### Phase 3: Implementation Pattern
+
+**Vanilla System.Callable** (flat args, no Open Interface coupling):
+
+**Read `assets/pattern_callable_vanilla.cls`** before generating — use when callers pass flat args and no VlocityOpenInterface integration is required.
+
+**Callable skeleton** (same inputs as VlocityOpenInterface):
+
+**Read `assets/pattern_callable_openinterface.cls`** before generating — use `inputMap` and `options` keys in `args` when integrating with Open Interface or when callers pass that structure.
+
+**Input format**: Callers pass `args` as `{ 'inputMap' => Map<String, Object>, 'options' => Map<String, Object> }`. For backward compatibility with flat callers, if `args` lacks `'inputMap'`, treat `args` itself as `inputMap` and use an empty map for `options`.
+
+**Implementation rules**:
+1. Keep `call()` thin; delegate to private methods or service classes
+2. Validate and coerce input types early (null-safe)
+3. Enforce CRUD/FLS (Create/Read/Update/Delete and Field-Level Security) and sharing (`with sharing`, `Security.stripInaccessible()`)
+4. Bulkify when args include record collections
+5. Use `WITH USER_MODE` for SOQL when appropriate
+6. **Namespace handling**: `System.Callable` is a standard interface (no namespace prefix required); `omnistudio.VlocityOpenInterface2` uses the managed `omnistudio` package namespace — always qualify it. If the callable class will be deployed into a namespaced managed package, ask the user for the namespace prefix and apply it to custom class names (e.g., `myns__Industries_XxxCallable`)
+
+**VlocityOpenInterface / VlocityOpenInterface2 implementation**:
+
+When implementing `omnistudio.VlocityOpenInterface` or `omnistudio.VlocityOpenInterface2`, use the signature:
+
+```apex
+global Boolean invokeMethod(String methodName, Map<String, Object> inputMap,
+                           Map<String, Object> outputMap, Map<String, Object> options)
+```
+
+**Read `assets/pattern_openinterface.cls`** before generating — complete `VlocityOpenInterface2` skeleton with `switch on` dispatch and `outputMap` contract.
+
+Open Interface implementation rules:
+- Write results into `outputMap` via `putAll()` or individual `put()` calls; do not return the envelope from `invokeMethod`
+- Return `true` for success, `false` for unsupported or failed actions
+- Use the same internal private methods as the Callable (same `inputMap` and `options` parameters); only the entry point differs
+- Populate `outputMap` with the same envelope shape (`success`, `data`, `errors`) for consistency
+
+Both Callable and Open Interface accept the same inputs (`inputMap`, `options`) and delegate to identical private method signatures for shared logic.
+
+---
+
+### Phase 4: Testing & Validation
+
+Minimum tests:
+- **Positive**: Supported action executes successfully
+- **Negative**: Unsupported action throws expected exception
+- **Contract**: Missing/invalid inputs return error envelope
+- **Bulk**: Handles list inputs without hitting limits
+
+**Read `assets/pattern_test_class.cls`** — complete test class skeleton (positive, negative, contract, bulk, and null-args cases) before generating tests.
+
+---
+
+## Migration: VlocityOpenInterface to System.Callable
+
+When modernizing Industries extensions, move `VlocityOpenInterface` or
+`VlocityOpenInterface2` implementations to `System.Callable` and keep the
+action contract stable.
+
+**Guidance**:
+- Preserve action names (`methodName`) as `action` strings in `call()`
+- Pass `inputMap` and `options` as keys in `args`: `{ 'inputMap' => inputMap, 'options' => options }`
+- Return a consistent response envelope instead of mutating `outMap`
+- Keep `call()` thin; delegate to the same internal methods with `(inputMap, options)` signature
+- Add tests for each action and unsupported action
+
+**Read `assets/pattern_migration.cls`** — annotated before/after migration example (VlocityOpenInterface2 → System.Callable) before starting migration work.
+
+---
+
+## Best Practices (120-Point Scoring)
+
+| Category | Points | Key Rules |
+|----------|--------|-----------|
+| **Contract & Dispatch** | 20 | Explicit action list; `switch on`; versioned action strings |
+| **Input Validation** | 20 | Required keys validated; types coerced safely; null guards |
+| **Security** | 20 | `with sharing`; CRUD/FLS checks; `Security.stripInaccessible()` |
+| **Error Handling** | 15 | Typed exceptions; consistent error envelope; no empty catch |
+| **Bulkification & Limits** | 20 | No SOQL/DML in loops; supports list inputs |
+| **Testing** | 15 | Positive/negative/contract/bulk tests |
+| **Documentation** | 10 | ApexDoc (`/** ... */` block comments — Salesforce Apex documentation standard) for class and action methods |
+
+**Thresholds**: ✅ 90+ (Ready) | ⚠️ 70-89 (Review) | ❌ <70 (Block)
+
+---
+
+## ⛔ Guardrails (Mandatory)
+
+Stop and ask the user if any of these would be introduced:
+- Dynamic method execution based on user input (no reflection)
+- SOQL/DML inside loops
+- `without sharing` on callable classes
+- Silent failures (empty catch, swallowed exceptions)
+- Inconsistent response shapes across actions
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|-----------|
+| Caller passes flat args but code expects `inputMap` key | Guard defensively: if `args` lacks `'inputMap'` key, treat `args` itself as the input map |
+| `call()` receives `null` for `args` | Always null-check `args` before accessing keys; initialize to empty map if null |
+| Test class uses `(Map<String, Object>) svc.call(...)` but call returns a wrong type | Ensure every action returns the same envelope type (`Map<String, Object>`) — mixed return types break callers |
+| VlocityOpenInterface2 migration breaks callers that read `outputMap` by reference | After migrating to Callable, callers must read the return value instead of reading `outputMap` — update all callers |
+| `IndustriesCallableException` class missing in project | This custom exception must be deployed alongside the callable class — include it in every deployment package |
+| Org has both legacy Open Interface and new Callable wired to same action | Only one entry point should be active at a time; disable the old interface after confirming the callable works |
+
+---
+
+## Common Anti-Patterns
+
+- `call()` contains business logic instead of delegating
+- Action names are unversioned or not documented
+- Input maps assumed to have keys without checks
+- Mixed response types (sometimes Map, sometimes String)
+- No tests for unsupported actions
+
+---
+
+## Cross-Skill Integration
+
+| Skill | When to Use | Example |
+|-------|-------------|---------|
+| generating-apex | General Apex work beyond callable implementations | "Create trigger for Account" |
+| generating-custom-object / generating-custom-field | Verify object/field availability before coding | "Describe Product2 fields" |
+| deploying-metadata | Validate/deploy callable classes | "Deploy to sandbox" |
+
+---
+
+## Reference Skill
+
+Use the core Apex standards, testing patterns, and guardrails in:
+- [skills/generating-apex/SKILL.md](../generating-apex/SKILL.md)
+
+---
+
+## Bundled Examples
+
+- [examples/Test_QuoteByProductCallable/](examples/Test_QuoteByProductCallable/) — read-only query example with `WITH USER_MODE`
+- [examples/Test_VlocityOpenInterfaceConversion/](examples/Test_VlocityOpenInterfaceConversion/) — migration from legacy `VlocityOpenInterface`
+- [examples/Test_VlocityOpenInterface2Conversion/](examples/Test_VlocityOpenInterface2Conversion/) — migration from `VlocityOpenInterface2`
+
+## Output Expectations
+
+Deliverables produced by this skill:
+
+- `<ClassName>.cls` — Callable class implementing `System.Callable` with `switch on action` dispatch
+- `<ClassName>Test.cls` — Test class with positive, negative, contract, and bulk test methods
+- `IndustriesCallableException.cls` — Custom exception class (if not already present in the project)
+
+---
+
+## Notes
+
+- Prefer deterministic, side-effect-aware callable actions
+- Keep action contracts stable; introduce new actions for breaking changes
+- Avoid long-running work in synchronous callables; use async when needed
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `assets/pattern_callable_vanilla.cls` | Phase 3 — vanilla `System.Callable` skeleton (flat args, no Open Interface coupling) |
+| `assets/pattern_callable_openinterface.cls` | Phase 3 — `System.Callable` skeleton with `inputMap`/`options` args (Open Interface-compatible) |
+| `assets/pattern_openinterface.cls` | Phase 3 — `VlocityOpenInterface2` skeleton with `switch on` dispatch and `outputMap` contract |
+| `assets/pattern_test_class.cls` | Phase 4 — test class skeleton (positive, negative, contract, bulk, and null-args cases) |
+| `assets/pattern_migration.cls` | Migration — annotated before/after migration pattern (VlocityOpenInterface2 → System.Callable) |
+| `examples/Test_QuoteByProductCallable/Industries_QuoteByProductCallable.cls` | Phase 3 — complete callable implementation with `WITH USER_MODE` SOQL and error envelope |
+| `examples/Test_QuoteByProductCallable/Industries_QuoteByProductCallableTest.cls` | Phase 4 — full test class covering positive, contract, and unsupported-action cases |
+| `examples/Test_QuoteByProductCallable/IndustriesCallableException.cls` | Phase 3 — custom exception pattern for unsupported actions |
+| `examples/Test_QuoteByProductCallable/TRANSCRIPT.md` | Reference — reasoning transcript for the Quote-by-Product callable example |
+| `examples/Test_VlocityOpenInterfaceConversion/MyCustomCallable.cls` | Phase 3 — migration pattern from legacy `VlocityOpenInterface` |
+| `examples/Test_VlocityOpenInterfaceConversion/MyCustomCallableTest.cls` | Phase 4 — test class for VlocityOpenInterface migration example |
+| `examples/Test_VlocityOpenInterfaceConversion/IndustriesCallableException.cls` | Phase 3 — custom exception class deployed alongside VlocityOpenInterface conversion |
+| `examples/Test_VlocityOpenInterfaceConversion/MyCustomVlocityOpenInterface2.cls` | Phase 3 — the original legacy VlocityOpenInterface2 class before migration |
+| `examples/Test_VlocityOpenInterfaceConversion/TRANSCRIPT.md` | Reference — reasoning transcript for VlocityOpenInterface conversion |
+| `examples/Test_VlocityOpenInterface2Conversion/MyCustomCallable.cls` | Phase 3 — migration pattern from `VlocityOpenInterface2` |
+| `examples/Test_VlocityOpenInterface2Conversion/MyCustomCallableTest.cls` | Phase 4 — test class for VlocityOpenInterface2 migration example |
+| `examples/Test_VlocityOpenInterface2Conversion/IndustriesCallableException.cls` | Phase 3 — custom exception class deployed alongside VlocityOpenInterface2 conversion |
+| `examples/Test_VlocityOpenInterface2Conversion/MyCustomRemoteClass.cls` | Phase 3 — remote class used by the VlocityOpenInterface2 migration example |
+| `examples/Test_VlocityOpenInterface2Conversion/TRANSCRIPT.md` | Reference — reasoning transcript for VlocityOpenInterface2 conversion |