description: "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)."
Design-time metadata tree for one Agentforce agent: planner → topics → actions → flows → Apex → prompts → NGA plugins. Reads declared metadata only — `BotDefinition`, `GenAiPlanner*`, `GenAiPlugin*`, `GenAiFunction*`, `Flow`, `ApexClass`, `GenAiPromptTemplate`. Does **not** read runtime audit rows.
**Runtime budget: 30–45s typical, ≤60s hard cap** on reference fixtures. Sequential baseline would be 90–220s; parallel Tooling SOQL fan-out delivers a 3–5× speedup. Large bots with many flows scale approximately linearly — each flow metadata retrieve is one round-trip.
Runs **inline** — no subagent. Every phase is deterministic file processing.
## If the user hasn't given enough to proceed
When invoked with no `agent_api_name` AND no org alias, print the following block **verbatim** — do not paraphrase, do not pre-run any script. Trigger condition: `$ARGUMENTS` is empty OR names no agent (no `--agent` flag and no known agent API name in the prose) OR names no org (no `--org` flag and no known alias).
> Which agent should I document, and in which org?
>
> I need:
> - **Agent API name** — the `DeveloperName` of the `BotDefinition` (e.g. `MyAgent`, `MySalesAgent`). Not the label.
> - **Org alias** — for `sf` CLI auth (the alias you configured with `sf org login`)
>
> Optional:
> - **Version** — an `agent_version_api_name` like `v5`. If omitted, I'll resolve the active `BotVersion`.
> - **`--reprobe`** — re-run the 7-day channel-probe cache (only needed after a Salesforce release).
>
> I'll run the metadata pipeline inline. Artifacts land under `~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent_api_name>__<agent_version>/` (overridable with `--data-dir`).
## Pipeline invocation
When the user has supplied `--org <alias>` + `--agent <api_name>` (plus any optional flags), run this block. One `python3` invocation drives the full pipeline. `main.py` writes `.emit_ctx.json`; `emit_result.py` reads it and prints the final `=== RESULT ===` block last to stdout.
```bash
set -euo pipefail
# zsh arrays are 1-indexed by default; bash arrays are 0-indexed.
# This block uses 0-indexed semantics throughout (_args[$i] starting at i=0),
# so under zsh + `set -u` the very first read of `_args[0]` would trip
# `parameter not set`. KSH_ARRAYS makes zsh treat arrays as 0-indexed,
# matching the bash shebang's expectation. No-op under bash.
| `max_mermaid_nodes` | `--max-mermaid-nodes` | no | 80 |
| `data_dir` | `--data-dir` | no | `~/.vibe/data/agentforce-architecture-analyze` |
| `cache_dir` | `--cache-dir` | no | `~/.vibe/cache/agentforce-architecture-analyze` |
## Outputs
All artifacts under `~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent_api_name>__<agent_version>/` (default; override with `--data-dir <path>`):
```
<agent>_<ver>_metadata_tree.json primary artifact — normalized planner/topic/action/flow/apex/prompt/plugin tree
<agent>_<ver>_architecture.md human-readable section-by-section rendering (H1 + 7 numbered sections, plus a conditional Dependency graph appendix). Mermaid diagrams are embedded inside the relevant sections (Action tree, Data flow, and Dependency graph)
```
## Pipeline — inline, no subagent
```
resolve_bot.py → BotDefinition + BotVersion + planner name lookup
retrieve_planner.py → Metadata API zip retrieve for GenAiPlannerBundle (+ NGA plugins if present)
parallel_retrieve.py → 6 parallel Tooling SOQL channels fan out from the planner id
(resolved by the `planner_definition_by_agent_chain` seed query):
parse_bundle.py → parse retrieved XML into normalized node shapes
parse_wave.py → BFS expansion: flow/apex/prompt refs discovered in nodes
→ SOQL for Flow/Apex bodies (batched by id list)
→ Metadata retrieve ONLY for GenAiPromptTemplate (+ NGA external plugins conditionally)
finalize.py → merge waves into metadata_tree.json
render_architecture.py → <agent>_<ver>_architecture.md + Mermaid invocation graph (capped at --max-mermaid-nodes)
```
**Channel strategy — SOQL-first.**
- **Tooling SOQL** for every normalized tree node (planner, plugins, functions, plugin-functions, plugin-instructions, planner-functions, planner-attrs) — 6 parallel channels keyed on planner id, plus the `planner_definition_by_agent_chain` seed query that resolves the planner id from the agent chain.
- **Data API SOQL** for Flow (by id) and Apex (by id or name) bodies — batched.
- **Metadata retrieve** only for two cases: (a) `GenAiPromptTemplate` (prompt bodies aren't cleanly exposed via Tooling SOQL), and (b) NGA **external plugins** when the planner is Native Generative Agent shape (skipped for classic ReAct).
This is where the 3–5× speedup comes from. A naive implementation would retrieve everything via Metadata API zips sequentially; parallel Tooling SOQL covers ~80% of the tree in a single fan-out.
## Planner shapes — classic ReAct vs NGA
The skill normalizes two planner families into a single tree shape:
| **Classic ReAct** | `ReactAiPlannerV1` / `SequentialPlannerIntentClassifier` / etc. | DeveloperName strings | no |
| **NGA** | `ConcurrentMultiAgentOrchestration` / `AnthropicCompatibleV1` / etc. | Sometimes 15/18-char Ids (ID-prefix routed) | yes (external plugins via Metadata retrieve) |
The ID-prefix router in `resolve_invocation_target.py` distinguishes the two: NGA InvocationTargets that look like ids (`01p…` = ApexClass, `301…` = Flow, etc.) get resolved via id-scoped SOQL; DeveloperName targets go through name-scoped SOQL. Unknown prefixes surface as `_unresolved[]` with `reason="unknown-id-prefix:<prefix>"` — never silently dropped.
## Caching
- **Tree cache**: `metadata_tree.json` is reused unless `--force` is passed. Cache key includes the asset-hash of every `.soql` / `.yaml` / `.mmd` template bundled with the skill — bump a template, the cache busts automatically.
- **Channel probe cache**: 7-day TTL on the per-org `sf sobject describe` results that validate every field name the SOQL assets reference. A Salesforce quarterly release that renames / removes a field triggers `status: PROBE_FAILED`; `--reprobe` forces a refresh.
## Prerequisites
| Tool | Required |
|---|---|
| `sf` CLI (authenticated against the target org) | yes — `sf org login web --alias <alias>` |
| Python 3.10+ | yes |
## Reference docs to load when needed
Do NOT load eagerly. Load when the user's question requires it:
-`references/soql_fields.md` — per-sObject field reference for the 13 sObjects this skill touches (2 Data API + 11 Tooling), with `[mandatory]` vs `[optional]` tags. Load when the user asks about a specific field, or when debugging an `INVALID_FIELD` SOQL error.
-`references/contract.json` — machine-readable schema for `metadata_tree.json`. Load when writing downstream tooling that consumes the tree.
-`references/architecture_sections.md` — section-by-section structure of the rendered `<agent>_<ver>_architecture.md`.
## Invariants worth knowing upfront
- **Pipeline is deterministic.** Same `(org, agent, version)` + static org metadata → byte-identical `<agent>_<ver>_metadata_tree.json` and `<agent>_<ver>_architecture.md`. Only manifest timestamps drift across re-runs.
- **Forward-only traversal.** Every discovered ref goes forward from planner → children. No backward lookups.
- **Partial results are surfaced, not silenced.** Any unresolved reference lands in `_unresolved[]` with `reason=...`. `STATUS=PARTIAL_OK` if any channel failed; `STATUS=OK` only on a clean run.
- **Cycle detection is per-branch.** Same flow visited along its own ancestor chain emits `_cycle_back_to:<path>` instead of recursing. A defensive `MAX_BFS_DEPTH=20` guard backs the per-branch ancestor set; real-world agents bottom out well before either limit fires. (Earlier docs claimed a hard cap of 5; that was the historical limit and was abandoned because shared utility flows like `handleFlowFault` tripped it on every nested tree — see `config.MAX_BFS_DEPTH` for the rationale.)
- **Child ordering is alphabetical by `api_name` (case-insensitive).** Topics come before non-topic plannerActions at the root level. Flow-actionCall order is NOT sorted — that's the flow author's execution sequence.
