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/architecture_sections.md

View on GitHub
# architecture.md section reference

Per-section rendering spec for `scripts/render_architecture.py::render`.
One `# Architecture` H1, seven numbered `## N. ...` sections, plus one
conditional "Dependency graph" appendix. Source of truth: the
`metadata_tree.json` schema produced by `scripts/parse_wave.py` at the
end of phase 9.

**Source of truth: the live tree** — field shapes evolve as parse_wave
learns new agent generations. When this doc disagrees with the
`metadata_tree.json` written by `parse_wave.py` for an actual agent on
your machine (under `~/.vibe/data/agentforce-architecture-analyze/<org>/<agent>__<ver>/`),
trust the live tree.

The Mermaid templates live at `assets/mermaid/*.mmd` and are the sole
consumer of the renderer helpers; each `{{PARAM}}` contract is
documented in the template's own header comment.

---

## Per-diagram node caps

Default caps (override via `render(..., max_mermaid_nodes={...})`):

| Diagram kind | Default cap | Over-cap behaviour |
|---|---|---|
| `flowchart` | 200 | summary placeholder + top-5 fan-out + catalog pointer |
| `stateDiagram` | 40 | summary placeholder (no fan-out — states are not nodes) |
| `sequenceDiagram` | 60 | summary placeholder + top-5 fan-out |
| `graph` | 100 | summary placeholder + top-5 fan-out |

Cap is measured in rendered elements (nodes + edges for flowchart/graph,
messages for sequenceDiagram, states + transitions for stateDiagram).
Above cap, the renderer emits a `> [diagram truncated: ...]` blockquote
with the element count, the top-5 nodes by fan-out (when applicable),
and a pointer to the catalog section that enumerates the same data
without compression.

---

## 1. Header + agent overview

**Purpose**: identify the agent and its planner in a single kv table.

**Input fields** (`tree.agent.*`):

- `api_name` — agent developer name
- `version` — `v<N>` label
- `master_label` — human-readable name
- `description` — prose summary
- `agent_type` — `EinsteinAgentKind` / `EinsteinCopilotForSalesforce` / …
- `type` — `ExternalCopilot` / `InternalCopilot` / …
- `agent_template`
- `bot_source`
- `generation` — `classic` / `nga` / `search` / `byop`
- `planner_name`
- `planner_type`
- `bot_id`

Plus `tree._schema_version`.

**Output shape**: `# <H1>` with api_name + version, followed by a 2-col
markdown table.

**Empty/degenerate cases**:

- Missing `api_name` / `version` renders `?` in the H1 (not `None`).
- Any missing field renders `-` in its row — not empty, because GitHub
 table rendering collapses empty cells and the row loses alignment.

---

## 2. Anatomy summary

**Purpose**: one-paragraph executive summary plus health callouts.

**Input fields**:

- `tree._kind_counts` — preferred source for topic / action / flow /
 apex / prompt counts.
- `tree.depth`, `tree.node_count` — size metrics.
- `tree._partial`, `tree._partial_reason` — health flag + prose reason.
- `tree._pending_fetches` — `{"FLOW":[...],"APEX":[...],
 "PROMPT_TEMPLATE":[...],"STANDARD_ACTION":[...]}`. Count determines
 the "pending fetches: N" line in the callout.
- `tree._unresolved` — triggers a second warn callout with the count.
- `tree.agent.planner_name` — missing -> warn callout.

**Output shape**: `## 2. Anatomy summary` + paragraph + zero-to-three
blockquote callouts. Callouts render as `> **Health: PARTIAL.**` /
`> **Health: WARN.**` prefixes with bullet sub-lines.

**Empty/degenerate cases**: if `_kind_counts` is absent, the walker
supplies counts from its own pass over the tree. Zero topics is valid
(SequentialPlannerIntentClassifier).

---

## 3. Action tree

**Purpose**: the full declared action tree as a flowchart with per-topic
subgraphs, plus a deterministic ASCII appendix for diff review.

**Input fields**:

- Walker-derived `topics[]` -> one subgraph per topic.
- Walker-derived `edges[]` -> `parent_api_name --> child_api_name`.
- `node._cycle_back_to` -> dotted back-edge `A -.->|cycle_back_to: X| B`.
- Planner-level actions (top-level `GEN_AI_FUNCTION` with no parent
 topic) -> synthetic `_plannerActions` subgraph.

**Output shape**: ` ```mermaid ` block with `flowchart TB` + subgraphs
+ edges, followed by a `<details>` with ASCII-tree appendix. When
above cap, the mermaid block is replaced with the truncation
placeholder; the ASCII appendix still renders.

**Empty/degenerate cases**:

- No topics, no planner actions -> `%% no topics` + `%% no edges`
 mermaid comments; diagram still parses.
- Cycle annotations render in both the mermaid (dotted edge) and the
 ASCII appendix (`[cycle]` marker on the node line).

---

## 4. Topic anatomy

**Purpose**: per-topic detail dump. One H3 per topic with a bullet list
of actions.

**Input fields**:

- Walker-derived `topics[]` with `api_name`, `label`, `actions`.
- `topic.raw.master_label` (preferred) or api_name for the label.

**Output shape**: `## 4. Topic anatomy` + one `### \`<api_name>\``
block per topic + kv list (`- Label:`, `- Action count:`, `- Actions:`
with sub-bullets).

**Empty/degenerate cases**: 0 topics -> `_No topics defined (planner
exposes actions directly)._` italic fallback. This is the expected
case for `SequentialPlannerIntentClassifier`.

---

## 5. Action catalog

**Purpose**: flat markdown table of every declared action.

**Input fields**:

- Walker-derived `actions[]` with `api_name`, `topic`, `raw.unwraps_to`.

**Output shape**: 3-col table (`Action | Topic | Unwraps to`). Unwraps
column renders as `KIND \`api_name\`` when `unwraps_to` is present, `-`
otherwise. Planner-level actions show `(plannerAction)` in the topic
column.

**Empty/degenerate cases**: no actions -> `_No actions declared._`
italic fallback.

---

## 6. Data flow / context propagation

**Purpose**: show which slot values propagate from user utterance
through the planner into each action.

**Input fields**:

- Walker-derived `topics[]` and `actions[]`.
- `action.raw.planner_attr.variable_name` + `planner_attr.data_type` —
 labels the edge `A -->|var: Type| B`. When absent, the edge is bare.

**Output shape**: `flowchart LR` via `load_mermaid("data_flow", ...)`.
Skeleton: `User` -> `Planner` -> each `Topic` -> each `Action` under
that topic.

**Empty/degenerate cases**: no planner_attr metadata -> every edge is
bare. 0 topics -> only `User --> Planner` renders (no action-level
edges). Above cap -> truncation placeholder.

---

## 7. Flow / Apex / Prompt catalogs

**Purpose**: per-artifact detail section for every backing flow, apex
class, and prompt template referenced by any action.

**Input fields**:

- Walker-derived `flows{}`, `apex{}`, `prompts{}`, keyed on api_name.
- `node.signature` (or `_signature` fallback) — signature block.

**Output shape**: `### Flows` / `### Apex classes` / `### Prompt
templates` H3 buckets, each containing `#### \`<api_name>\`` + a fenced
signature block or `_Signature not captured._` fallback. Prompt
templates render as a flat bullet list (signature capture is
per-template prose, not a flow/apex shape).

**Empty/degenerate cases**: no backing artifacts in the tree ->
`_No backing artifacts in tree._` italic fallback.

---

## 8. Unresolved refs + artifact pointers

**Purpose**: surface every `_unresolved[]` entry and point at the
sidecar files the reader can open.

**Input fields**:

- `tree._unresolved[]` — list of `{kind, api_name, reason}` records.

**Output shape**: Either a 3-col `Kind | Api name | Reason` table or
an `_No unresolved references._` italic fallback. Followed by an
`### Artifact pointers` sub-heading with a bullet list of relative
paths (tree JSON, manifest, summary).

**Empty/degenerate cases**: always renders — the artifact-pointer list
is unconditional.

---

## Conditional: Dependency graph

**Purpose**: rendered only when `tree._unresolved[]` is non-empty OR
the tree contains cycle annotations. Shows cross-artifact dependencies
plus the unresolved nodes as dashed-outline markers.

**Input fields**:

- Walker-derived `edges[]`.
- `tree._unresolved[]` — each becomes a `:::unresolved` styled node.
- Walker-derived `cycles[]` — each becomes a dotted back-edge.

**Output shape**: `graph LR` via `load_mermaid("dependency_graph",
...)`. Includes a `classDef unresolved` class marker at the bottom of
the template so unresolved nodes render with `stroke-dasharray`.

**Empty/degenerate cases**: not rendered at all when both conditions
are false. Above the `graph` cap -> truncation placeholder replaces
the mermaid block.
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