forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-architecture-analyze
agentforce-architecture-analyze
VerifiedDeclared 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).
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()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |