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

scripts/summarize_tree.py

View on GitHub
#!/usr/bin/env python3
"""Render the declared action tree as a box-drawing summary.md.

Called by finalize.py (cold path) and cache_check.py (hit path when the
cached summary is missing). Mirrors the old agent Phase 7 render_tree()
logic verbatim.

Usage:
    python3 summarize_tree.py <tree_json_path> <out_md_path> <built_at_utc>

Inputs:
    argv[1]   absolute path to declared_action_tree.json (or similar)
    argv[2]   output .summary.md path (overwritten atomically)
    argv[3]   ISO-8601 UTC built-at timestamp (e.g. 2026-04-25T14:00:00Z)

Outputs:
    argv[2]   rendered markdown
    exit 0    success
    exit 1    missing args, read failure, write failure
"""
import json
import os
import pathlib
import sys

KC_ORDER = [
    "BOT_DEFINITION", "TOPIC", "GEN_AI_FUNCTION",
    "FLOW", "APEX", "PROMPT_TEMPLATE",
    "STANDARD_ACTION", "UNKNOWN",
]


def render_tree(node, prefix="", is_last=True, lines=None, agent_=None):
    if lines is None:
        lines = []
    connector = "└── " if is_last else "├── "
    kind = node.get("kind", "?")
    api = node.get("api_name", "?")
    elem = node.get("element_name")
    if kind == "BOT_DEFINITION":
        v = (agent_ or {}).get("version") or ""
        label = f"[{kind}] {api}" + (f" ({v})" if v else "")
    elif kind == "GEN_AI_FUNCTION":
        unwraps = node.get("unwraps_to") or {}
        uk = unwraps.get("kind")
        un = unwraps.get("api_name")
        arrow = f" → {uk}:{un}" if uk and un else ""
        label = f"[{kind}] {api}{arrow}"
    elif kind in ("STANDARD_ACTION", "UNKNOWN"):
        # Canonical key is `invocation_type` (schema 3.1+); fall back to
        # the two legacy keys so caches built by an older parse_wave still
        # render the qualifier.
        raw = (
            node.get("invocation_type")
            or node.get("raw_invocation_type")
            or node.get("raw_action_type")
            or ""
        )
        label = f"[{kind}] {api}" + (f" ({raw})" if raw else "")
    else:
        label = f"[{kind}] {api}"
    if elem and kind != "BOT_DEFINITION":
        label += f"  — element:{elem}"
    lines.append(prefix + connector + label)
    children = node.get("children") or []
    child_prefix = prefix + ("    " if is_last else "│   ")
    for i, c in enumerate(children):
        render_tree(c, child_prefix, i == len(children) - 1, lines, agent_)
    return lines


def main() -> int:
    if len(sys.argv) != 4:
        sys.stderr.write(
            "summarize_tree.py: usage: python3 summarize_tree.py <tree_json_path> "
            "<out_md_path> <built_at_utc>\n"
        )
        return 1

    tree_path = pathlib.Path(sys.argv[1])
    out_path = pathlib.Path(sys.argv[2])
    built_at = sys.argv[3]

    try:
        tree = json.loads(tree_path.read_text())
    except (OSError, json.JSONDecodeError) as e:
        sys.stderr.write(f"summarize_tree.py: cannot read {tree_path}: {e}\n")
        return 1

    a = tree.get("agent", {}) or {}
    kc = tree.get("_kind_counts", {}) or {}

    lines = [
        f"# {a.get('api_name', '?')} {a.get('version', '?')} — declared action tree",
        "",
        f"- **Bot ID:** `{a.get('bot_id', '?')}`",
        f"- **Master label:** {a.get('master_label', '?')}",
        f"- **Generation:** {a.get('generation', 'unknown')}",
        f"- **Planner:** `{a.get('planner_name', '?')}` ({a.get('planner_type', '?')})",
        f"- **Version auto-picked:** {a.get('_version_auto_picked', False)}",
        f"- **Built at (UTC):** {built_at}",
        f"- **Node count:** {tree.get('node_count', 0)}",
        f"- **Depth:** {tree.get('depth', 0)}",
        f"- **Partial:** {tree.get('_partial', False)}",
        "",
        "## Kind counts",
        "",
    ]
    for k in KC_ORDER:
        lines.append(f"- `{k}`: {kc.get(k, 0)}")

    lines += [
        "",
        "## Declared action tree",
        "",
        "```",
    ]
    root = tree.get("root") or {"kind": "BOT_DEFINITION", "api_name": a.get("api_name", "?"), "children": []}
    lines.extend(render_tree(root, "", True, None, a))
    lines.append("```")

    if tree.get("_unresolved"):
        lines += ["", "## Unresolved", ""]
        for u in tree["_unresolved"]:
            lines.append(
                f"- `{u.get('kind')}`/`{u.get('api_name')}` — {u.get('reason')}"
            )

    content = "\n".join(lines) + "\n"

    try:
        out_path.parent.mkdir(parents=True, exist_ok=True)
        tmp = out_path.with_suffix(out_path.suffix + ".tmp")
        tmp.write_text(content)
        os.replace(tmp, out_path)
    except OSError as e:
        sys.stderr.write(f"summarize_tree.py: write failed: {e}\n")
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())
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