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_finalize.py

View on GitHub
"""Tests for ``finalize`` — declared-action-tree finalization + cache write.

Covers:
- ``sort_tree_in_place``  pure tree mutation (TOPIC-first, alphabetical-by-api_name)
- ``main``                WORK_DIR / DATA_DIR / CACHE_DIR orchestration

The pure-function tests build small dict trees inline. ``main`` tests
construct a minimal WORK_DIR layout under ``tmp_path`` so the orchestration
runs end-to-end without any external metadata fixtures.
"""
from __future__ import annotations

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

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

import finalize  # type: ignore


# -----------------------------------------------------------------------------
# sort_tree_in_place — pure tree mutation
# -----------------------------------------------------------------------------


class SortTreeInPlaceTests(unittest.TestCase):
    """Per docstring: TOPIC nodes first, then non-topic plannerActions.
    Within each tier, sorted by kind then api_name (case-insensitive).
    Each TOPIC's own children: alphabetical by api_name (case-insensitive).
    FLOW children are NOT sorted.
    """

    def test_empty_tree_is_noop(self):
        root = {}
        finalize.sort_tree_in_place(root)
        self.assertEqual(root, {})

    def test_root_with_no_children_is_noop(self):
        root = {"children": []}
        finalize.sort_tree_in_place(root)
        self.assertEqual(root["children"], [])

    def test_non_dict_root_is_safe(self):
        # Non-dict input shouldn't blow up.
        finalize.sort_tree_in_place(None)  # type: ignore[arg-type]
        finalize.sort_tree_in_place([])  # type: ignore[arg-type]

    def test_topics_come_before_non_topics_at_root(self):
        root = {"children": [
            {"kind": "STANDARD_ACTION", "api_name": "actA"},
            {"kind": "TOPIC", "api_name": "topicZ"},
            {"kind": "APEX", "api_name": "apexA"},
            {"kind": "TOPIC", "api_name": "topicA"},
        ]}
        finalize.sort_tree_in_place(root)
        kinds = [c["kind"] for c in root["children"]]
        # Two TOPICs first, then non-topics
        self.assertEqual(kinds[:2], ["TOPIC", "TOPIC"])
        self.assertNotIn("TOPIC", kinds[2:])

    def test_topics_sort_alphabetical_case_insensitive(self):
        root = {"children": [
            {"kind": "TOPIC", "api_name": "Zeta"},
            {"kind": "TOPIC", "api_name": "alpha"},
            {"kind": "TOPIC", "api_name": "Beta"},
        ]}
        finalize.sort_tree_in_place(root)
        names = [c["api_name"] for c in root["children"]]
        self.assertEqual(names, ["alpha", "Beta", "Zeta"])

    def test_non_topics_sort_by_kind_then_name(self):
        root = {"children": [
            {"kind": "STANDARD_ACTION", "api_name": "z_act"},
            {"kind": "APEX", "api_name": "z_apex"},
            {"kind": "STANDARD_ACTION", "api_name": "a_act"},
            {"kind": "APEX", "api_name": "a_apex"},
        ]}
        finalize.sort_tree_in_place(root)
        # Tier 1 sorted by (kind, api_name): APEX rows before STANDARD_ACTION
        kinds = [c["kind"] for c in root["children"]]
        self.assertEqual(kinds, ["APEX", "APEX", "STANDARD_ACTION", "STANDARD_ACTION"])
        names_apex = [c["api_name"] for c in root["children"][:2]]
        self.assertEqual(names_apex, ["a_apex", "z_apex"])

    def test_topic_children_sorted_alphabetical_case_insensitive(self):
        root = {"children": [{
            "kind": "TOPIC",
            "api_name": "T1",
            "children": [
                {"kind": "STANDARD_ACTION", "api_name": "Zebra"},
                {"kind": "STANDARD_ACTION", "api_name": "apple"},
                {"kind": "STANDARD_ACTION", "api_name": "Banana"},
            ],
        }]}
        finalize.sort_tree_in_place(root)
        names = [c["api_name"] for c in root["children"][0]["children"]]
        self.assertEqual(names, ["apple", "Banana", "Zebra"])

    def test_topic_with_no_children_is_safe(self):
        root = {"children": [{"kind": "TOPIC", "api_name": "T1"}]}
        finalize.sort_tree_in_place(root)
        self.assertEqual(root["children"][0]["api_name"], "T1")

    def test_missing_api_name_treated_as_empty(self):
        # Should sort to the front under casefold of empty string.
        root = {"children": [
            {"kind": "TOPIC", "api_name": "Beta"},
            {"kind": "TOPIC"},  # no api_name
        ]}
        finalize.sort_tree_in_place(root)
        names = [c.get("api_name", "") for c in root["children"]]
        self.assertEqual(names[0], "")  # empty/missing comes first


# -----------------------------------------------------------------------------
# main — orchestration via env vars + WORK_DIR
# -----------------------------------------------------------------------------


def _build_workdir(tmp: Path, *, planner_name: str = "MyPlanner",
                   pending: dict | None = None,
                   unresolved: list | None = None) -> tuple[Path, Path, Path]:
    """Construct a minimal WORK_DIR + DATA_DIR + CACHE_DIR triple.

    Returns (work_dir, data_dir, cache_dir). Caller passes these as env
    vars before invoking finalize.main().
    """
    work_dir = tmp / "work"
    data_dir = tmp / "data" / "ALPHA0000000000" / "MyAgent__v1"
    cache_dir = tmp / "cache" / "ALPHA0000000000" / "MyAgent__v1"
    work_dir.mkdir(parents=True)

    tree = {
        "agent": {"api_name": "MyAgent", "version": "v1"},
        "node_count": 1,
        "depth": 1,
        "_schema_version": "3.1",
        "_kind_counts": {"TOPIC": 1},
        "_pending_fetches": pending or {},
        "_unresolved": unresolved or [],
        "root": {"children": [{"kind": "TOPIC", "api_name": "Greetings"}]},
    }
    (work_dir / "declared_action_tree.json").write_text(json.dumps(tree))
    return work_dir, data_dir, cache_dir


class MainTests(unittest.TestCase):

    def _run_main(self, work_dir: Path, data_dir: Path, cache_dir: Path,
                  *, planner_name: str = "MyPlanner") -> int:
        old = dict(os.environ)
        os.environ.update({
            "WORK_DIR": str(work_dir),
            "DATA_DIR": str(data_dir),
            "CACHE_DIR": str(cache_dir),
            "AGENT_API_NAME": "MyAgent",
            "AGENT_VERSION": "v1",
            "PLANNER_NAME": planner_name,
        })
        try:
            return finalize.main()
        finally:
            os.environ.clear()
            os.environ.update(old)

    def test_main_writes_tree_and_manifest_and_returns_zero(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            work_dir, data_dir, cache_dir = _build_workdir(tmp)
            rc = self._run_main(work_dir, data_dir, cache_dir)
            self.assertEqual(rc, 0)
            tree_file = data_dir / "MyAgent_v1_metadata_tree.json"
            self.assertTrue(tree_file.exists())
            self.assertTrue((data_dir / "last_built_at.txt").exists())
            manifest = json.loads((cache_dir / "manifest.json").read_text())
            self.assertEqual(manifest["agent"]["api_name"], "MyAgent")
            self.assertEqual(manifest["partial"], False)
            self.assertEqual(manifest["unresolved_count"], 0)

    def test_main_marks_partial_when_planner_name_empty(self):
        # Empty PLANNER_NAME → _partial=True, _partial_reason="no-planner".
        with TemporaryDirectory() as t:
            tmp = Path(t)
            work_dir, data_dir, cache_dir = _build_workdir(tmp)
            rc = self._run_main(work_dir, data_dir, cache_dir, planner_name="")
            self.assertEqual(rc, 0)
            tree = json.loads(
                (data_dir / "MyAgent_v1_metadata_tree.json").read_text()
            )
            self.assertTrue(tree["_partial"])
            self.assertEqual(tree["_partial_reason"], "no-planner")

    def test_main_marks_partial_when_unresolved_present(self):
        # Planner OK, _pending empty, but _unresolved non-empty
        # → _partial=True, _partial_reason="unresolved-refs".
        with TemporaryDirectory() as t:
            tmp = Path(t)
            work_dir, data_dir, cache_dir = _build_workdir(
                tmp, unresolved=[{"reason": "404"}]
            )
            rc = self._run_main(work_dir, data_dir, cache_dir)
            self.assertEqual(rc, 0)
            tree = json.loads(
                (data_dir / "MyAgent_v1_metadata_tree.json").read_text()
            )
            self.assertTrue(tree["_partial"])
            self.assertEqual(tree["_partial_reason"], "unresolved-refs")

    def test_main_marks_partial_when_pending_present(self):
        # Planner OK, _unresolved empty, but _pending non-empty
        # → _partial=True, _partial_reason="pending-refs".
        with TemporaryDirectory() as t:
            tmp = Path(t)
            work_dir, data_dir, cache_dir = _build_workdir(
                tmp, pending={"flows": ["FlowA"]}
            )
            rc = self._run_main(work_dir, data_dir, cache_dir)
            self.assertEqual(rc, 0)
            tree = json.loads(
                (data_dir / "MyAgent_v1_metadata_tree.json").read_text()
            )
            self.assertTrue(tree["_partial"])
            self.assertEqual(tree["_partial_reason"], "pending-refs")

    def test_main_returns_one_when_env_missing(self):
        old = dict(os.environ)
        # Wipe required envs. Set only one.
        for k in ("WORK_DIR", "DATA_DIR", "CACHE_DIR",
                  "AGENT_API_NAME", "AGENT_VERSION"):
            os.environ.pop(k, None)
        try:
            rc = finalize.main()
        finally:
            os.environ.clear()
            os.environ.update(old)
        self.assertEqual(rc, 1)

    def test_main_returns_one_when_tree_json_missing(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            work_dir = tmp / "work"
            data_dir = tmp / "data"
            cache_dir = tmp / "cache"
            work_dir.mkdir()
            # No declared_action_tree.json — finalize should bail.
            rc = self._run_main(work_dir, data_dir, cache_dir)
            self.assertEqual(rc, 1)

    def test_main_strips_visited_from_durable_artifact(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            work_dir, data_dir, cache_dir = _build_workdir(tmp)
            tree_path = work_dir / "declared_action_tree.json"
            tree = json.loads(tree_path.read_text())
            tree["_visited"] = {"some": "internal-state"}
            tree_path.write_text(json.dumps(tree))
            rc = self._run_main(work_dir, data_dir, cache_dir)
            self.assertEqual(rc, 0)
            written = json.loads(
                (data_dir / "MyAgent_v1_metadata_tree.json").read_text()
            )
            self.assertNotIn("_visited", written)

    def test_main_seeds_gitignore_on_data_and_cache_roots(self):
        with TemporaryDirectory() as t:
            tmp = Path(t)
            work_dir, data_dir, cache_dir = _build_workdir(tmp)
            self._run_main(work_dir, data_dir, cache_dir)
            # data_dir.parent.parent == tmp/data; cache_dir.parent.parent == tmp/cache
            self.assertTrue((data_dir.parent.parent / ".gitignore").exists())
            self.assertTrue((cache_dir.parent.parent / ".gitignore").exists())


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