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/tests/test_summarize_tree.py

View on GitHub
"""Tests for ``summarize_tree`` — declared-action-tree → markdown summary.

Covers:
- ``render_tree``  recursive box-drawing renderer
- ``main``         CLI orchestration via argv (tree_json + out_md + built_at)
"""
from __future__ import annotations

import json
import unittest
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest import mock

from . import _bootstrap  # noqa: F401  — sys.path setup

import summarize_tree  # type: ignore


# -----------------------------------------------------------------------------
# render_tree — pure dict → list[str]
# -----------------------------------------------------------------------------


class RenderTreeTests(unittest.TestCase):

    def test_single_leaf_uses_last_connector(self):
        # is_last=True (default) → "└── "; no children → no recursion.
        out = summarize_tree.render_tree({"kind": "TOPIC", "api_name": "T1"})
        self.assertEqual(out, ["└── [TOPIC] T1"])

    def test_first_of_two_siblings_uses_branch_connector(self):
        # render at top-level isn't the natural use, but the function
        # accepts is_last=False → "├── ".
        out = summarize_tree.render_tree(
            {"kind": "TOPIC", "api_name": "T1"}, is_last=False
        )
        self.assertEqual(out, ["├── [TOPIC] T1"])

    def test_bot_definition_with_version_includes_version_in_label(self):
        agent = {"version": "v3"}
        out = summarize_tree.render_tree(
            {"kind": "BOT_DEFINITION", "api_name": "MyAgent"},
            agent_=agent,
        )
        self.assertEqual(out, ["└── [BOT_DEFINITION] MyAgent (v3)"])

    def test_bot_definition_without_version_omits_version_suffix(self):
        out = summarize_tree.render_tree(
            {"kind": "BOT_DEFINITION", "api_name": "MyAgent"},
            agent_={},
        )
        self.assertEqual(out, ["└── [BOT_DEFINITION] MyAgent"])

    def test_gen_ai_function_includes_unwraps_arrow(self):
        out = summarize_tree.render_tree({
            "kind": "GEN_AI_FUNCTION",
            "api_name": "GAF1",
            "unwraps_to": {"kind": "FLOW", "api_name": "FlowA"},
        })
        self.assertEqual(out, ["└── [GEN_AI_FUNCTION] GAF1 → FLOW:FlowA"])

    def test_gen_ai_function_without_unwraps_omits_arrow(self):
        out = summarize_tree.render_tree({
            "kind": "GEN_AI_FUNCTION",
            "api_name": "GAF1",
        })
        self.assertEqual(out, ["└── [GEN_AI_FUNCTION] GAF1"])

    def test_standard_action_uses_invocation_type_when_present(self):
        out = summarize_tree.render_tree({
            "kind": "STANDARD_ACTION",
            "api_name": "SA1",
            "invocation_type": "standardinvocableaction",
        })
        self.assertEqual(
            out, ["└── [STANDARD_ACTION] SA1 (standardinvocableaction)"]
        )

    def test_standard_action_falls_back_to_legacy_invocation_keys(self):
        # raw_invocation_type wins when invocation_type missing.
        with self.subTest("raw_invocation_type"):
            out = summarize_tree.render_tree({
                "kind": "STANDARD_ACTION",
                "api_name": "SA1",
                "raw_invocation_type": "legacyA",
            })
            self.assertIn("legacyA", out[0])
        with self.subTest("raw_action_type"):
            out = summarize_tree.render_tree({
                "kind": "UNKNOWN",
                "api_name": "U1",
                "raw_action_type": "legacyB",
            })
            self.assertIn("legacyB", out[0])

    def test_element_name_appended_for_non_bot_kinds(self):
        out = summarize_tree.render_tree({
            "kind": "FLOW",
            "api_name": "FlowA",
            "element_name": "callX",
        })
        self.assertEqual(out, ["└── [FLOW] FlowA  — element:callX"])

    def test_element_name_skipped_on_bot_definition(self):
        out = summarize_tree.render_tree({
            "kind": "BOT_DEFINITION",
            "api_name": "MyAgent",
            "element_name": "should-not-appear",
        }, agent_={"version": "v1"})
        self.assertNotIn("should-not-appear", out[0])

    def test_nested_children_recurse_with_correct_prefix(self):
        out = summarize_tree.render_tree({
            "kind": "TOPIC",
            "api_name": "T1",
            "children": [
                {"kind": "STANDARD_ACTION", "api_name": "A1"},
                {"kind": "STANDARD_ACTION", "api_name": "A2"},
            ],
        })
        # Top-level (is_last=True) gets " " continuation prefix.
        self.assertEqual(out, [
            "└── [TOPIC] T1",
            "    ├── [STANDARD_ACTION] A1",
            "    └── [STANDARD_ACTION] A2",
        ])

    def test_branch_node_uses_pipe_continuation_for_children(self):
        # is_last=False at parent → "│ " continuation prefix.
        out = summarize_tree.render_tree({
            "kind": "TOPIC",
            "api_name": "T1",
            "children": [{"kind": "APEX", "api_name": "A1"}],
        }, is_last=False)
        self.assertEqual(out, [
            "├── [TOPIC] T1",
            "│   └── [APEX] A1",
        ])


# -----------------------------------------------------------------------------
# main — argv-based CLI
# -----------------------------------------------------------------------------


def _minimal_tree() -> dict:
    return {
        "agent": {
            "api_name": "MyAgent", "version": "v1", "bot_id": "0Xx000000000",
            "master_label": "My Agent", "generation": "nga",
            "planner_name": "MyPlanner", "planner_type": "Atlas__Reasoning",
            "_version_auto_picked": False,
        },
        "node_count": 2,
        "depth": 1,
        "_kind_counts": {"TOPIC": 1, "STANDARD_ACTION": 1},
        "_partial": False,
        "root": {
            "kind": "BOT_DEFINITION", "api_name": "MyAgent",
            "children": [{"kind": "TOPIC", "api_name": "Greetings"}],
        },
    }


class MainTests(unittest.TestCase):

    def test_main_returns_one_when_argv_count_wrong(self):
        with mock.patch.object(summarize_tree, "sys") as fake_sys:
            fake_sys.argv = ["summarize_tree.py"]  # missing args
            fake_sys.stderr.write = lambda *_a, **_kw: None
            rc = summarize_tree.main()
        self.assertEqual(rc, 1)

    def test_main_returns_one_when_tree_json_unreadable(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            with mock.patch.object(summarize_tree, "sys") as fake_sys:
                fake_sys.argv = [
                    "summarize_tree.py",
                    str(tmp / "missing.json"),
                    str(tmp / "out.md"),
                    "2026-05-09T00:00:00Z",
                ]
                fake_sys.stderr.write = lambda *_a, **_kw: None
                rc = summarize_tree.main()
            self.assertEqual(rc, 1)

    def test_main_writes_summary_md_with_expected_sections(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            tree_path = tmp / "tree.json"
            tree_path.write_text(json.dumps(_minimal_tree()))
            out_path = tmp / "out.summary.md"

            with mock.patch.object(summarize_tree, "sys") as fake_sys:
                fake_sys.argv = [
                    "summarize_tree.py",
                    str(tree_path), str(out_path),
                    "2026-05-09T00:00:00Z",
                ]
                fake_sys.stderr.write = lambda *_a, **_kw: None
                rc = summarize_tree.main()

            self.assertEqual(rc, 0)
            content = out_path.read_text()
            self.assertIn("# MyAgent v1 — declared action tree", content)
            self.assertIn("## Kind counts", content)
            self.assertIn("## Declared action tree", content)
            # tree section is wrapped in ``` fence
            self.assertIn("```\n└── [BOT_DEFINITION] MyAgent (v1)", content)
            # 2026-05-09 timestamp surfaced
            self.assertIn("2026-05-09T00:00:00Z", content)

    def test_main_appends_unresolved_section_when_present(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            tree = _minimal_tree()
            tree["_unresolved"] = [
                {"kind": "FLOW", "api_name": "Missing", "reason": "404"},
            ]
            tree_path = tmp / "tree.json"
            tree_path.write_text(json.dumps(tree))
            out_path = tmp / "out.summary.md"

            with mock.patch.object(summarize_tree, "sys") as fake_sys:
                fake_sys.argv = [
                    "summarize_tree.py",
                    str(tree_path), str(out_path),
                    "2026-05-09T00:00:00Z",
                ]
                fake_sys.stderr.write = lambda *_a, **_kw: None
                summarize_tree.main()

            content = out_path.read_text()
            self.assertIn("## Unresolved", content)
            self.assertIn("`FLOW`/`Missing` — 404", content)


if __name__ == "__main__":
    unittest.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