Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-architecture-analyze

agentforce-architecture-analyze

Verified

Declared architecture snapshot for one Agentforce agent: planner, topics, actions, flows, Apex, prompt templates, and NGA plugins. Renders a human-readable architecture document and Mermaid invocation graph from design-time metadata (not runtime audit rows). TRIGGER when user asks to describe, diagram, inventory, audit, document, or diff (e.g. v3 vs v5) the architecture / action tree / topic structure / tool inventory of a specific agent by agent API name in a specific org. DO NOT TRIGGER for runtime session traces, conversation transcripts, generation timings, or gateway audit chains — this skill reads design-time metadata only (use agentforce-d360-analyze for session traces).

FileKindSize
README.mdmarkdown8.5 KB
SKILL.mdskill md17.5 KB
assets/cli/describe_sobject.yamlconfig317 B
assets/cli/describe_tooling_sobject.yamlconfig347 B
assets/cli/list_metadata_genaiprompttemplate.yamlconfig342 B
assets/cli/org_display.yamlconfig280 B
assets/cli/retrieve_genai_plugin.yamlconfig391 B
assets/cli/show_access_token.yamlconfig700 B
assets/mermaid/action_tree.mmdother986 B
assets/mermaid/data_flow.mmdother893 B
assets/mermaid/dependency_graph.mmdother810 B
assets/mermaid/invocation_sequence.mmdother1004 B
assets/mermaid/planner_state.mmdother813 B
assets/soql/apex_class_bodies_by_ids.soqlother103 B
assets/soql/apex_class_bodies_by_names.soqlother102 B
assets/soql/bot_definition_details.soqlother152 B
assets/soql/bot_version_lookup.soqlother186 B
assets/soql/flow_definition_by_ids.soqlother115 B
assets/soql/flow_definition_ids_by_names.soqlother146 B
assets/soql/flow_definition_view_by_durable_ids.soqlother180 B
assets/soql/flow_metadata_by_id.soqlother73 B
assets/soql/functions_by_plugins.soqlother317 B
assets/soql/planner_attrs_by_parent_ids.soqlother156 B
assets/soql/planner_bundle_functions.soqlother93 B
assets/soql/planner_definition_by_agent_chain.soqlother174 B
assets/soql/plugin_functions_by_plugin_ids.soqlother93 B
assets/soql/plugin_instructions_by_plugin_ids.soqlother168 B
assets/soql/plugins_by_planner.soqlother199 B
references/architecture_sections.mdmarkdown8.3 KB
references/contract.jsonconfig11.7 KB
references/soql_fields.mdmarkdown24.6 KB
scripts/_shared/__init__.pyscript82 B
scripts/_shared/fs_guard.pyexecutablescript12.8 KB
scripts/_shared/paths.pyscript3.9 KB
scripts/_shared/runtime.pyscript2.0 KB
scripts/_shared/sql.pyscript355 B
scripts/cache_check.pyexecutablescript8.9 KB
scripts/config.pyscript5.9 KB
scripts/emit_env.pyexecutablescript5.1 KB
scripts/emit_result.pyexecutablescript10.7 KB
scripts/fetch_soql.pyscript26.1 KB
scripts/finalize.pyexecutablescript11.8 KB
scripts/main.pyscript113.9 KB
scripts/metadata_listing.pyscript9.5 KB
scripts/parallel_retrieve.pyscript3.3 KB
scripts/parse_bundle.pyexecutablescript7.9 KB
scripts/parse_wave.pyexecutablescript36.1 KB
scripts/probe_channels.pyscript11.1 KB
scripts/render_architecture.pyscript40.0 KB
scripts/resolve_bot.pyexecutablescript9.4 KB
scripts/resolve_invocation_target.pyscript4.8 KB
scripts/rest_client.pyscript33.7 KB
scripts/retrieve_planner.pyscript464 B
scripts/sanitize.pyexecutablescript1013 B
scripts/sf_cli.pyscript12.3 KB
scripts/soql_loader.pyscript11.1 KB
scripts/summarize_tree.pyexecutablescript4.6 KB
scripts/tests/__init__.pyscript0 B
scripts/tests/_bootstrap.pyscript843 B
scripts/tests/fixtures/__init__.pyscript0 B
scripts/tests/fixtures/genai_payloads.pyscript12.5 KB
scripts/tests/test_cache_check.pyscript12.6 KB
scripts/tests/test_cache_check_main.pyscript10.4 KB
scripts/tests/test_config.pyscript3.8 KB
scripts/tests/test_end_to_end_fixture.pyscript26.2 KB
scripts/tests/test_finalize.pyscript11.2 KB
scripts/tests/test_flow_children_inflation.pyscript25.6 KB
scripts/tests/test_fs_guard.pyscript4.3 KB
scripts/tests/test_iterative_wave_b.pyscript19.0 KB
scripts/tests/test_main_pipeline.pyscript145.1 KB
scripts/tests/test_parallel_retrieve.pyscript4.8 KB
scripts/tests/test_parse_bundle.pyscript15.6 KB
scripts/tests/test_parse_wave.pyscript26.9 KB
scripts/tests/test_parse_wave_classifiers.pyscript8.6 KB
scripts/tests/test_parse_wave_helpers.pyscript14.3 KB
scripts/tests/test_parse_wave_main.pyscript16.4 KB
scripts/tests/test_per_branch_visited.pyscript9.5 KB
scripts/tests/test_probe_channels.pyscript13.3 KB
scripts/tests/test_probe_cli_recipes.pyscript8.2 KB
scripts/tests/test_render_architecture.pyscript32.7 KB
scripts/tests/test_resolve_bot.pyscript7.5 KB
scripts/tests/test_resolve_creds.pyscript12.0 KB
scripts/tests/test_resolve_invocation_target.pyscript5.2 KB
scripts/tests/test_rest_client.pyscript49.8 KB
scripts/tests/test_runtime_override.pyscript3.9 KB
scripts/tests/test_sf_cli.pyscript17.3 KB
scripts/tests/test_signature_stamping.pyscript18.0 KB
scripts/tests/test_skill_md_pipeline_block.pyscript12.7 KB
scripts/tests/test_soql_loader.pyscript21.3 KB
scripts/tests/test_summarize_tree.pyscript8.9 KB
scripts/tests/test_write_emit_ctx.pyscript19.2 KB
scripts/write_emit_ctx.pyexecutablescript14.1 KB

references/soql_fields.md

View on GitHub
# sObject field reference — architecture skill

Field reference for the 13 sObjects this skill queries across the 15
SOQL templates under `assets/soql/`. Two are reached via the Data API
(`BotDefinition`, `BotVersion`); the remaining 11 are Tooling-only.

**Source of truth: the live org** (`sf sobject describe --sobject <Name>
[--use-tooling-api]`). Schemas verified against live Salesforce API
v66.0 via `sf sobject describe` on `my-org-alias` + `my-org-alias-2`,
2026-05-02. Official Salesforce Help pages describe logical structures
that frequently diverge from the physical fields the REST / Tooling API
actually expose. When a Help page disagrees with a live describe, trust
the live describe — the names in this reference are what you query.

The source of truth for "mandatory" is `scripts/probe_channels.py`'s
`MANDATORY_FIELDS` map. A probe that sees any `[mandatory]` field
missing flips to `status: "PROBE_FAILED"` — the skill aborts with a
clean error rather than producing a subtly-wrong tree. `[optional]`
fields degrade gracefully — missing ones are recorded but don't block
the run.

---

## Casing gotchas

- **Mixed case is mandatory for `GenAi*` sObjects.** API names are
 `GenAiPlannerDefinition`, `GenAiPluginDefinition`, `GenAiFunctionDefinition`,
 `GenAiPluginFunctionDef`, `GenAiPluginInstructionDef`,
 `GenAiPlannerFunctionDef`, `GenAiPlannerAttrDefinition`. Lowercase
 variants (`genai_planner_definition`, `genaiplannerdefinition`) do not
 resolve. The SOQL parser is case-insensitive on keywords but
 sObject + field names must match the describe output for Tooling API
 calls to route correctly.
- **`GenAiPluginFunctionDef` vs `GenAiPlannerFunctionDef` are different
 tables.** Plugin-scope join (topic → function, via `PluginId`) vs
 planner-bundle-scope join (planner → function, via `PlannerId`). Both
 are 10-field join tables with nearly identical shape; keep them
 straight.
- **`BotVersion.DeveloperName` is the version id, not the version
 label.** `DeveloperName` on BotVersion is the version API name (e.g.
 `v5`), used as the second path segment under
 `<org_id15>/<agent>__<version>/`. `MasterLabel` is the
 human-readable label (e.g. "Version 5 — ported from staging"). Never
 mix them — the data dir layout and the SKILL.md input contract both
 key on `DeveloperName`.
- **`complexvalue` fields require single-row retrieval.** `Metadata`
 (on `Flow`, `FlowDefinition`, `GenAiPluginDefinition`,
 `GenAiFunctionDefinition`), `SymbolTable` (on `ApexClass`), and
 `AgentGraph` (on `GenAiPlannerDefinition`, often null in practice) are
 `complexvalue` types. Salesforce enforces
 `MALFORMED_QUERY: When retrieving results with Metadata or FullName
 fields, the query qualifications must specify no more than one row for
 retrieval.` Batch IN-clause SELECTs that return ≥2 rows fail. Use a
 single-row equality (`WHERE Id = '<id>'`) per fetch; parallelize
 across ids via `concurrent.futures`. `ApexClass.Body` +
 `ApexClass.SymbolTable` is the one notable exception: the
 `Name IN (...)` batch works even though `SymbolTable` is complex.

---

## Cross-sObject join map

Every edge is strictly **forward** from the entry query
(`GenAiPlannerDefinition WHERE DeveloperName = :planner_name`). No
backward lookups.

```text
BotDefinition (Data API, PK Id, matched by DeveloperName)
 └── BotVersion (Data API, FK BotDefinitionId)
 │ [resolved to planner name via Bot metadata retrieve]
 ▼
GenAiPlannerDefinition (Tooling, PK Id, matched by DeveloperName)
 │
 ├── GenAiPluginDefinition ← WHERE PlannerId = :plannerId
 │ ├── GenAiPluginInstructionDef ← WHERE GenAiPluginDefinitionId IN (:topic_ids)
 │ ├── GenAiPluginFunctionDef ← WHERE PluginId IN (:topic_ids)
 │ │ └── Function picklist → GenAiFunctionDefinition.Id
 │ └── GenAiFunctionDefinition ← WHERE PluginId IN (:topic_ids)
 │
 ├── GenAiPlannerFunctionDef ← WHERE PlannerId = :plannerId
 │ └── Plugin picklist → GenAiPluginDefinition.Id (or external via retrieve)
 │
 ├── GenAiFunctionDefinition ← WHERE PluginId IN (:topic_ids)
 │ │ (single-query — see functions_by_plugins.soql)
 │ │
 │ └── InvocationTargetType + InvocationTarget route to:
 │ ├── flow → FlowDefinition (batch IN) → Flow.Metadata (parallel single-row)
 │ ├── apex → ApexClass (batch IN, Body + SymbolTable)
 │ ├── standardInvocableAction → (no further fetch — declared only)
 │ └── generatePromptResponse → GenAiPromptTemplate (Metadata API retrieve)
 │
 └── GenAiPlannerAttrDefinition ← WHERE ParentId IN (:function_ids, :planner_id)
 (polymorphic ParentId: GenAiFunctionDefinition OR GenAiPlannerDefinition)
```

Per-channel row counts + `_unresolved[]` reasons are recorded in
`metadata_tree.json` under `_channels` and `_unresolved` keys.

---

## Data API sObjects (2)

### `BotDefinition` (Data API) — one row per agent

Root of the agent metadata. Matched by `DeveloperName`; the rest of the
tree is resolved forward from the `BotVersion` child.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `DeveloperName` | string | no | yes | [mandatory] |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `AgentType` | picklist | yes | yes | [optional] — discriminator for classic vs NGA in some orgs |
| `Type` | picklist | yes | yes | [optional] |
| `AgentTemplate` | string | yes | yes | [optional] — e.g. `SvcCopilotTmpl__EinsteinAgentKind` |
| `BotSource` | picklist | yes | yes | [optional] |
| `AgentUser` | reference | yes | yes | [optional] — FK to `User` |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `LastModifiedDate` | datetime | no | yes | [optional] |
| `SystemModstamp` | datetime | no | yes | [optional] |

### `BotVersion` (Data API) — one row per agent version

Resolves the active version (or user-pinned version) for a given bot.
Parent relationship: `BotDefinition` via `BotDefinitionId`.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `BotDefinitionId` | reference | no | yes | [mandatory] |
| `DeveloperName` | string | no | yes | [optional] — version id (e.g. `v5`) |
| `MasterLabel` | string | yes | yes | [optional] — human label |
| `Status` | picklist | yes | yes | [optional] — `Active` on the current published version |
| `VersionNumber` | int | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `AiReplyRecordVisibility` | picklist | yes | yes | [optional] |
| `ResponseDelayMilliseconds` | int | yes | yes | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `LastModifiedDate` | datetime | no | yes | [optional] |

---

## Tooling API sObjects (11)

All sObjects in this section are reachable via the Tooling API only
(`sf data query --use-tooling-api` or `sf sobject describe --use-tooling-api`).

### `ApexClass` (Tooling) — Apex source + parsed AST

Source + full method/property AST for Apex referenced by
`GenAiFunctionDefinition.InvocationTarget` when
`InvocationTargetType = 'apex'`. Batch-safe on `Name IN (...)` or
`Id IN (...)` (despite `SymbolTable` being `complexvalue`, Salesforce
permits the batch for this particular sObject — verified live).

**Note:** `SymbolTable` is **not part of `FIELDS(ALL)`** and must be
named explicitly in the SELECT.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `Name` | string | no | yes | [mandatory] |
| `Body` | textarea | yes | no | [optional] — full Apex source |
| `SymbolTable` | complexvalue | yes | no | [optional] — parsed AST (methods, params, annotations, line/col) |
| `ApiVersion` | double | no | yes | [optional] |
| `IsValid` | boolean | no | yes | [optional] |
| `Status` | picklist | no | yes | [optional] |
| `LengthWithoutComments` | int | yes | yes | [optional] |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `FullName` | string | yes | no | [optional] — complexvalue companion |
| `Metadata` | complexvalue | yes | no | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `LastModifiedDate` | datetime | no | yes | [optional] |
| `SystemModstamp` | datetime | no | yes | [optional] |

**Single-row requirement for complexvalue columns:** `Metadata` and
`FullName` on `ApexClass` follow the standard `MALFORMED_QUERY` rule —
batch IN-clause SELECTs that return ≥2 rows fail when these two are
selected. `Body` + `SymbolTable` are the exception (batch works).
Comments in `assets/soql/apex_class_bodies_by_ids.soql` +
`apex_class_bodies_by_names.soql` pin this.

### `Flow` (Tooling) — Flow version body

Single-row retrieval required — `Metadata` and `FullName` are both
`complexvalue`. Fired once per `activeVersionId` returned by
`FlowDefinition`; parallelized via `ThreadPoolExecutor`.

**Filterability quirk:** `FullName` is selectable but **not filterable**
(`INVALID_FIELD: field 'FullName' can not be filtered in a query call`).
Filter by `Id` instead.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `DefinitionId` | reference | no | yes | [mandatory] |
| `FullName` | string | yes | **no** | [optional] — complexvalue companion; not filterable |
| `Metadata` | complexvalue | yes | no | [optional] — full flow JSON (actionCalls, subflows, variables, decisions, formulas, assignments, apexPluginCalls) |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `VersionNumber` | int | yes | yes | [optional] |
| `ProcessType` | picklist | yes | yes | [optional] |
| `Status` | picklist | yes | yes | [optional] |
| `ApiVersion` | double | yes | yes | [optional] |
| `IsActive` | boolean | no | yes | [optional] |
| `IsTemplate` | boolean | no | yes | [optional] |
| `RunInMode` | picklist | yes | yes | [optional] |
| `Environments` | picklist | yes | yes | [optional] |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `OverriddenFlowId` | reference | yes | yes | [optional] |
| `SourceTemplateId` | reference | yes | yes | [optional] |
| `TriggerType` | picklist | yes | yes | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `LastModifiedDate` | datetime | no | yes | [optional] |
| `SystemModstamp` | datetime | no | yes | [optional] |
| `InstalledPackageName` | string | yes | yes | [optional] |

**Single-row requirement:** `Metadata` and `FullName` force
`WHERE Id = '<version_id>'`. The SOQL asset `flow_metadata_by_id.soql`
encodes this as a single `Id = '...'` predicate.

### `FlowDefinition` (Tooling) — Flow versioning index

Two-hop feeder to `Flow`. Batch IN-clause works. Returns
`ActiveVersionId` + `LatestVersionId` — the skill prefers active.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `DeveloperName` | string | no | yes | [mandatory] |
| `ActiveVersionId` | reference | yes | yes | [optional] — FK to `Flow.Id` |
| `LatestVersionId` | reference | yes | yes | [optional] — FK to `Flow.Id` |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `Metadata` | complexvalue | yes | no | [optional] — definition-level metadata (may carry what the Flow hop provides on some orgs) |
| `FullName` | string | yes | no | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `LastModifiedDate` | datetime | no | yes | [optional] |
| `SystemModstamp` | datetime | no | yes | [optional] |

### `GenAiPlannerDefinition` (Tooling) — planner root

Entry query for the tree. Matched by `DeveloperName` (the
`<genAiPlannerName>` extracted from the Bot metadata retrieve). The
`PlannerType` picklist is the classifier for classic ReAct vs NGA.

**Seven-value `PlannerType` picklist** (verified consistent across
`my-org-alias`, `my-org-alias-2`, `my-org-alias-3`): grouped by
namespace — `AiCopilot__*` = classic ReAct family,
`Atlas__*` = NGA family. `startswith("Atlas__")` is a clean
classic-vs-NGA discriminator.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `DeveloperName` | string | no | yes | [mandatory] |
| `PlannerType` | picklist | yes | yes | [mandatory] |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `Capabilities` | textarea | yes | no | [optional] — null in every row tested on both classic + NGA |
| `AgentGraph` | complexvalue | yes | no | [optional] — null in every row tested; single-row rule still applies |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `Metadata` | complexvalue | yes | no | [optional] |
| `FullName` | string | yes | no | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `LastModifiedDate` | datetime | no | yes | [optional] |
| `SystemModstamp` | datetime | no | yes | [optional] |

**Single-row requirement for complexvalue columns:** `AgentGraph`,
`Metadata`, `FullName` — select individually; entry query pins
`WHERE DeveloperName = '...' LIMIT 1`.

### `GenAiPluginDefinition` (Tooling) — topics

All topics for a planner via `WHERE PlannerId = :plannerId`. Carries
`PluginType` + `Scope` for topic classification and `CanEscalate` /
`IsLocal` for behavior flags.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `DeveloperName` | string | no | yes | [mandatory] |
| `PluginType` | picklist | yes | yes | [optional] — topic type classifier |
| `Scope` | textarea | yes | no | [optional] — natural-language topic scope |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `CanEscalate` | boolean | yes | yes | [optional] |
| `IsLocal` | boolean | yes | yes | [optional] |
| `Source` | picklist | yes | yes | [optional] |
| `ParentId` | reference | yes | yes | [optional] — planner FK (sometimes referred to as `PlannerId` in SOQL filter clauses) |
| `LocalDeveloperName` | string | yes | yes | [optional] |
| `Language` | picklist | yes | yes | [optional] |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `Metadata` | complexvalue | yes | no | [optional] |
| `FullName` | string | yes | no | [optional] |
| `ClassificationDescription` | textarea | yes | no | [optional] |
| `GenAiFunctionInvoker` | string | yes | yes | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |

**Single-row requirement:** `Metadata` + `FullName` require per-id
retrieval. The production path doesn't SELECT `Metadata` on this sObject
(see `plugins_by_planner.soql`) — it pulls `Scope` + scalar fields
instead, which batch-safely over `PlannerId = :id`.

### `GenAiPluginFunctionDef` (Tooling) — plugin-function join

Join table: `GenAiPluginDefinition` → `GenAiFunctionDefinition`. Batch-
safe on `PluginId IN (...)`.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `PluginId` | reference | no | yes | [mandatory] |
| `Function` | picklist | yes | yes | [optional] — references `GenAiFunctionDefinition.Id` |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `SystemModstamp` | datetime | no | yes | [optional] |

### `GenAiPluginInstructionDef` (Tooling) — per-topic instructions

Per-topic instruction text + ordering. Batch-safe on
`GenAiPluginDefinitionId IN (...)`.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `GenAiPluginDefinitionId` | reference | no | yes | [mandatory] |
| `DeveloperName` | string | no | yes | [optional] |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] — the instruction text |
| `SortOrder` | int | yes | yes | [optional] |
| `Language` | picklist | yes | yes | [optional] |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `FullName` | string | yes | no | [optional] |
| `Metadata` | complexvalue | yes | no | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |

**Single-row requirement:** `Metadata` + `FullName` complexvalue pair;
the production SOQL omits them (scalar fields batch-safely).

### `GenAiFunctionDefinition` (Tooling) — actions

The actions. Combined single-query fetches both bundle-scope (`PlannerId`)
and topic-scope (`PluginId IN`) functions. `InvocationTargetType`
+ `InvocationTarget` route to the downstream fetch (Flow, Apex, prompt,
standard invocable).

**`InvocationTarget` format varies by planner shape** (the ID-prefix
router lives in `scripts/resolve_invocation_target.py`):
- Classic ReAct: DeveloperName string (e.g. `AGNT_SetUserSelectedOption`).
- NGA: Salesforce 15/18-char Id (e.g. `01pVF...` = ApexClass,
 `300VF...` = FlowDefinition, `0hf...` = GenAiPromptTemplate).

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `DeveloperName` | string | no | yes | [mandatory] |
| `InvocationTarget` | string | yes | yes | [mandatory] |
| `InvocationTargetType` | picklist | yes | yes | [optional] — `flow` / `apex` / `standardInvocableAction` / `generatePromptResponse` |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `IsLocal` | boolean | yes | yes | [optional] |
| `IsConfirmationRequired` | boolean | yes | yes | [optional] |
| `IsIncludeInProgressIndicator` | boolean | yes | yes | [optional] |
| `ProgressIndicatorMessage` | string | yes | yes | [optional] |
| `Source` | picklist | yes | yes | [optional] |
| `PluginId` | reference | yes | yes | [optional] — topic-scope FK (null for bundle-scope functions) |
| `PlannerId` | reference | yes | yes | [optional] — bundle-scope FK (null on NGA — attachment is plugin-only) |
| `ParentId` | reference | yes | yes | [optional] |
| `LocalDeveloperName` | string | yes | yes | [optional] |
| `Language` | picklist | yes | yes | [optional] |
| `InvocationTargetApiName` | string | yes | yes | [optional] |
| `MissingValuePromptMessage` | string | yes | yes | [optional] |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `Metadata` | complexvalue | yes | no | [optional] |
| `FullName` | string | yes | no | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |

**Single-row requirement:** `Metadata` + `FullName` complexvalue
columns; production SOQL omits both to keep the `PlannerId / PluginId IN`
batch path intact.

### `GenAiPlannerFunctionDef` (Tooling) — planner-bundle join

Bundle-scope join: planner → function. Analogous to
`GenAiPluginFunctionDef` but keyed on `PlannerId`. Batch-safe on
`PlannerId = :id`.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `PlannerId` | reference | no | yes | [mandatory] |
| `Plugin` | picklist | yes | yes | [optional] — references plugin DeveloperName / id |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |
| `SystemModstamp` | datetime | no | yes | [optional] |

### `GenAiPlannerAttrDefinition` (Tooling) — parameter mappings

The `attributeMappings` — I/O parameter bindings between actions and
the planner. **Polymorphic `ParentId`**: points at either a
`GenAiFunctionDefinition` (function-scope mappings) or
`GenAiPlannerDefinition` (bundle-scope mappings). The production SOQL
passes the union of function ids + planner id via
`WHERE ParentId IN (:function_ids, :planner_id)`.

`MappingType` is the `input` / `output` picklist; `ParameterName`
identifies the bound variable on the planner side.

| Name | Type | Nillable | Filterable | Tag |
|---|---|---|---|---|
| `Id` | id | no | yes | [mandatory] |
| `ParentId` | reference | yes | yes | [optional] — polymorphic: GenAiFunctionDefinition \| GenAiPlannerDefinition |
| `DeveloperName` | string | no | yes | [optional] |
| `MasterLabel` | string | yes | yes | [optional] |
| `Description` | textarea | yes | no | [optional] |
| `MappingType` | picklist | yes | yes | [optional] — `input` / `output` |
| `ParameterName` | string | yes | yes | [optional] |
| `Language` | picklist | yes | yes | [optional] |
| `NamespacePrefix` | string | yes | yes | [optional] |
| `ManageableState` | picklist | yes | yes | [optional] |
| `IsDeleted` | boolean | no | yes | [optional] |
| `CreatedById` | reference | no | yes | [optional] |
| `CreatedDate` | datetime | no | yes | [optional] |
| `LastModifiedById` | reference | no | yes | [optional] |

---

## Known picklist values (live-API verified, 2026-05-02)

| sObject | Field | Values |
|---|---|---|
| `GenAiPlannerDefinition` | `PlannerType` | Seven values split by namespace. Classic family: `AiCopilot__ReAct`, `AiCopilot__ReactAiPlannerV1`, `AiCopilot__SequentialPlannerIntentClassifier`. NGA family: `Atlas__ConcurrentMultiAgentOrchestration`, `Atlas__AnthropicCompatibleV1`, `Atlas__AtlasReactV1`, `Atlas__MainSubAgent` (exact set may vary by release — `startswith("Atlas__")` is the stable classic-vs-NGA discriminator). |
| `GenAiFunctionDefinition` | `InvocationTargetType` | `flow`, `apex`, `standardInvocableAction`, `generatePromptResponse` |
| `GenAiPlannerAttrDefinition` | `MappingType` | `input`, `output` |
| `BotVersion` | `Status` | `Inactive`, `Active` (active = currently published version) |

---

## Mandatory-field enforcement

The `[mandatory]` tags above mirror `scripts/probe_channels.py`:

```python
MANDATORY_FIELDS: Dict[str, set[str]] = {
 "BotDefinition": {"Id", "DeveloperName"},
 "BotVersion": {"Id", "BotDefinitionId"},
 "ApexClass": {"Id", "Name"},
 "Flow": {"Id", "MasterLabel", "DefinitionId"},
 "FlowDefinition": {"Id", "DeveloperName"},
 "GenAiPlannerDefinition": {"Id", "DeveloperName", "PlannerType"},
 "GenAiPluginDefinition": {"Id", "DeveloperName"},
 "GenAiFunctionDefinition": {"Id", "DeveloperName", "InvocationTarget"},
 "GenAiPlannerAttrDefinition": {"Id"},
}
```

`GenAiPluginFunctionDef`, `GenAiPluginInstructionDef`, and
`GenAiPlannerFunctionDef` don't appear in `MANDATORY_FIELDS` — they're
join tables whose `Id` + FK columns are present by construction on
every query. The per-sObject tables above tag their FK columns as
`[mandatory]` because the SOQL assets SELECT them; a probe that saw
them missing would still flip `PROBE_FAILED` via the `Id` check, but
the tag reflects "the skill's SOQL will fail if this column is gone."

When a Salesforce quarterly release renames or removes a
`[mandatory]` field, run with `--reprobe` to force a fresh describe and
surface the drift cleanly.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall