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

View on GitHub
"""structural validation of the describe CLI recipes.

Before these recipes shipped, `scripts/probe_channels.py::_describe_sobject`
called `run_sf("describe_sobject", ...)` / `run_sf("describe_tooling_sobject",
...)` against YAMLs that didn't exist on disk. Every unit test mocked
`run_sf`, so the suite stayed green — but the first real invocation would
have raised `SfCliError: recipe not found`. This module closes that gap
by loading each YAML via `sf_cli._load_recipe` and asserting the schema
`sf_cli.run_sf` expects.

Deliberately does NOT invoke `sf sobject describe` — that needs a live
org. Structural validation only; the wire-level contract is covered by
the existing probe_channels integration path once the skill ships.
"""
from __future__ import annotations

import unittest
import unittest.mock as mock
from pathlib import Path

from . import _bootstrap  # noqa: F401

import sf_cli  # type: ignore

# SKILL_ROOT is now file-relative (config.py uses
# Path(__file__).resolve().parent.parent), so config.CLI_DIR auto-resolves
# to the repo's assets/cli/ under test. _REPO_CLI_DIR is kept for tests
# that compare paths or pass them as explicit args.
_REPO_CLI_DIR = (
    Path(__file__).resolve().parent.parent.parent / "assets" / "cli"
)


class DescribeRecipeStructureTests(unittest.TestCase):
    """Both describe recipes must parse + conform to the run_sf schema."""

    def setUp(self) -> None:
        # patch the module-level CLI_DIR binding inside sf_cli so
        # _load_recipe reads from the repo's assets/cli/. `sf_cli`
        # imported `CLI_DIR` by name at module load, so we must patch
        # the *local* reference in sf_cli — patching `config.CLI_DIR`
        # alone would leave the stale import behind.
        self._patch = mock.patch.object(sf_cli, "CLI_DIR", _REPO_CLI_DIR)
        self._patch.start()
        self.addCleanup(self._patch.stop)

    def _load(self, name: str) -> dict:
        # _load_recipe is the same function run_sf uses at runtime, so if
        # it parses here it will parse in production. yaml.safe_load + the
        # mapping-shape guard both run inside _load_recipe .
        return sf_cli._load_recipe(name)

    # ---- parsing + mapping shape -----------------------------------------

    def test_describe_sobject_parses(self):
        recipe = self._load("describe_sobject")
        self.assertIsInstance(recipe, dict)
        self.assertEqual(recipe.get("name"), "describe_sobject")

    def test_describe_tooling_sobject_parses(self):
        recipe = self._load("describe_tooling_sobject")
        self.assertIsInstance(recipe, dict)
        self.assertEqual(recipe.get("name"), "describe_tooling_sobject")

    # ---- required_params: a list, covers what probe_channels passes -------

    def test_required_params_are_list_of_strings(self):
        for name in ("describe_sobject", "describe_tooling_sobject"):
            with self.subTest(recipe=name):
                recipe = self._load(name)
                required = recipe.get("required_params")
                self.assertIsInstance(required, list)
                self.assertTrue(
                    all(isinstance(p, str) for p in required),
                    f"{name}: required_params must be list[str]",
                )
                # probe_channels._describe_sobject passes exactly these two.
                # If the recipe drops either, run_sf will SfCliError before
                # the subprocess call — so assert both are present.
                self.assertIn("ORG_ALIAS", required)
                self.assertIn("SOBJECT", required)

    # ---- argv: a list of strings with both placeholders referenced --------

    def test_argv_is_list_of_strings(self):
        for name in ("describe_sobject", "describe_tooling_sobject"):
            with self.subTest(recipe=name):
                recipe = self._load(name)
                argv = recipe.get("argv")
                self.assertIsInstance(argv, list)
                self.assertGreater(len(argv), 0)
                self.assertTrue(
                    all(isinstance(e, str) for e in argv),
                    f"{name}: argv must be list[str]",
                )

    def test_argv_references_both_required_placeholders(self):
        """Every key in required_params must appear as `{{KEY}}` somewhere
        in argv — otherwise the substitution is a no-op and the caller's
        input never reaches the CLI. Defensive sanity check, not a
        functional run.
        """
        for name in ("describe_sobject", "describe_tooling_sobject"):
            with self.subTest(recipe=name):
                recipe = self._load(name)
                argv_joined = " ".join(recipe["argv"])
                for key in recipe.get("required_params") or []:
                    self.assertIn(
                        f"{{{{{key}}}}}", argv_joined,
                        f"{name}: required param {key} not referenced in argv",
                    )

    # ---- success_check contract -----------------------------------------

    def test_success_check_is_stdout_json_status_zero(self):
        """run_sf's success-detection code path (in sf_cli.run_sf) assumes
        `stdout_json_status_zero`. Any other value silently changes the
        pass/fail contract, so pin it.
        """
        for name in ("describe_sobject", "describe_tooling_sobject"):
            with self.subTest(recipe=name):
                recipe = self._load(name)
                self.assertEqual(
                    recipe.get("success_check"), "stdout_json_status_zero",
                )

    # ---- timeout is a positive int ---------------------------------------

    def test_timeout_is_positive_int(self):
        for name in ("describe_sobject", "describe_tooling_sobject"):
            with self.subTest(recipe=name):
                recipe = self._load(name)
                t = recipe.get("timeout_seconds")
                self.assertIsInstance(t, int)
                self.assertGreater(t, 0)

    # ---- auth_required_stderr_patterns -----------------------------------

    def test_auth_patterns_cover_the_known_failures(self):
        """sf CLI surfaces `NoOrgAuthenticationError` for a never-logged-in
        alias and `AuthInfoError` for a stale/revoked session. Both must
        classify as AuthRequired, not a generic SfCliError, so the skill
        can prompt the user to re-login instead of aborting.
        """
        for name in ("describe_sobject", "describe_tooling_sobject"):
            with self.subTest(recipe=name):
                recipe = self._load(name)
                patterns = recipe.get("auth_required_stderr_patterns") or []
                self.assertIn("NoOrgAuthenticationError", patterns)
                self.assertIn("AuthInfoError", patterns)

    # ---- tooling recipe has --use-tooling-api; data-API recipe does NOT ---

    def test_tooling_recipe_uses_tooling_api_flag(self):
        recipe = self._load("describe_tooling_sobject")
        self.assertIn("--use-tooling-api", recipe["argv"])

    def test_data_api_recipe_does_not_use_tooling_api_flag(self):
        """Separating the two recipes rather than toggling via a param
        was a deliberate design call (call sites stay explicit). Verify
        the separation hasn't regressed into a single merged recipe.
        """
        recipe = self._load("describe_sobject")
        self.assertNotIn("--use-tooling-api", recipe["argv"])

    # ---- run_sf missing-param surfacing runs end-to-end through recipe ----

    def test_run_sf_raises_cleanly_when_required_param_absent(self):
        """This exercises the full load_recipe → required_params check
        path inside run_sf, with a REAL (on-disk) recipe rather than a
        mock. If the YAML parses but required_params is malformed, this
        would surface as something other than SfCliError with a clear
        'missing required params' message.
        """
        with self.assertRaises(sf_cli.SfCliError) as ctx:
            # Deliberately omit SOBJECT — should raise at the required-
            # params check, well before subprocess.run. Pass ORG_ALIAS so
            # we isolate the failure to the missing param.
            sf_cli.run_sf("describe_sobject", ORG_ALIAS="whatever")
        self.assertIn("missing required params", str(ctx.exception))
        self.assertIn("SOBJECT", str(ctx.exception))


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