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

View on GitHub
"""Run SKILL.md's "## Pipeline invocation" bash block under bash and zsh.

The block is the contract the agent executes verbatim, so these tests extract
it from SKILL.md (no copy to drift) and run it under ``env -i`` against:

* a stub SKILL_ROOT whose scripts/main.py records its argv, emit_result.py
  prints a RESULT marker, and _shared/fs_guard.py always passes;
* a stub ``sf`` on PATH that answers ``config get target-org --json`` with a
  canned payload (or fails).

Scenarios: ARGUMENTS unset with ARG_AGENT preset (default org used), flags in
ARGUMENTS, flags overriding preset ARG_*, nothing resolvable (usage, no
pipeline run), and SKILL_ROOT discovery when the scripts are staged under
``<candidate>/artifacts/`` (the ADK eval staging layout).
"""
from __future__ import annotations

import json
import os
import re
import shutil
import stat
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path

_SKILL_NAME = "agentforce-architecture-analyze"


def _find_skill_md() -> Path:
    # contributed-skills: <skill>/scripts/tests/ -> <skill>/SKILL.md
    # outputs/unified-sors: <skill>/artifacts/scripts/tests/ -> <skill>/SKILL.md
    for parent in Path(__file__).resolve().parents:
        candidate = parent / "SKILL.md"
        if candidate.is_file():
            return candidate
    raise FileNotFoundError("SKILL.md not found above " + __file__)


def _extract_pipeline_block(skill_md: str) -> str:
    section = skill_md.split("## Pipeline invocation", 1)[1]
    match = re.search(r"```bash\n(.*?)\n```", section, re.S)
    if match is None:
        raise ValueError("no ```bash block under '## Pipeline invocation'")
    return match.group(1) + "\n"


def _write_exec(path: Path, text: str) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(text)
    path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)


_RECORDER = """\
import json, os, sys
with open({record!r}, "a") as fh:
    fh.write(json.dumps({{"script": {name!r}, "path": os.path.realpath(__file__),
                         "argv": sys.argv[1:]}}) + "\\n")
{tail}
"""

_SF_STUB = """#!/bin/sh
# Canned `sf config get target-org --json`; behaviour chosen by SF_STUB_MODE.
if [ "$1 $2 $3" != "config get target-org" ]; then
  echo "unexpected sf call: $*" >&2; exit 3
fi
case "${SF_STUB_MODE:-set}" in
  set) cat <<'JSON'
{
  "status": 0,
  "result": [
    {
      "name": "target-org",
      "location": "Local",
      "value": "default-org",
      "success": true
    }
  ],
  "warnings": []
}
JSON
  ;;
  unset) printf '%s\\n' '{"status":0,"result":[{"name":"target-org","success":true}],"warnings":[]}' ;;
  fail) echo '{"status":1,"name":"Error"}'; exit 1 ;;
esac
"""


class PipelineBlockTest(unittest.TestCase):
    SHELLS = [s for s in ("bash", "zsh") if shutil.which(s)]

    @classmethod
    def setUpClass(cls) -> None:
        cls.block = _extract_pipeline_block(_find_skill_md().read_text())

    def setUp(self) -> None:
        self.tmp = Path(tempfile.mkdtemp(prefix="arch-block-test-"))
        self.addCleanup(shutil.rmtree, self.tmp, True)
        self.record = self.tmp / "calls.jsonl"
        self.root = self.tmp / "skill"
        self._make_stub_scripts(self.root)
        self.bin = self.tmp / "bin"
        _write_exec(self.bin / "sf", _SF_STUB)
        (self.bin / "python3").symlink_to(sys.executable)
        self.script = self.tmp / "block.sh"
        self.script.write_text(self.block)
        self.home = self.tmp / "home"
        self.home.mkdir()

    # -- helpers ---------------------------------------------------------

    def _make_stub_scripts(self, root: Path) -> Path:
        """Recorder stubs for main.py / emit_result.py / _shared/fs_guard.py
        under ``root/scripts``; returns that scripts dir."""
        scripts = root / "scripts"
        (scripts / "_shared").mkdir(parents=True)
        (scripts / "main.py").write_text(
            _RECORDER.format(record=str(self.record), name="main", tail="")
        )
        (scripts / "emit_result.py").write_text(
            _RECORDER.format(
                record=str(self.record), name="emit",
                tail='print("=== RESULT ===")',
            )
        )
        (scripts / "_shared" / "fs_guard.py").write_text(
            _RECORDER.format(record=str(self.record), name="fs_guard", tail="")
        )
        return scripts

    def _run(self, shell: str, extra_env: dict[str, str], with_sf: bool = True,
             skill_root: str | None = None):
        if self.record.exists():
            self.record.unlink()
        bin_dir = self.bin
        if not with_sf:
            bin_dir = self.tmp / "bin-nosf"
            bin_dir.mkdir(exist_ok=True)
            if not (bin_dir / "python3").exists():
                (bin_dir / "python3").symlink_to(sys.executable)
        env = {
            "PATH": f"{bin_dir}:/usr/bin:/bin",
            "HOME": str(self.home),
            **extra_env,
        }
        if skill_root is None:
            env["SKILL_ROOT"] = str(self.root)
        elif skill_root:
            env["SKILL_ROOT"] = skill_root
        # skill_root="" → SKILL_ROOT unset, so the install-root probe runs.
        cmd = ["env", "-i", *(f"{k}={v}" for k, v in env.items()),
               shell, str(self.script)]
        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
        calls = []
        if self.record.exists():
            calls = [json.loads(l) for l in self.record.read_text().splitlines()]
        for call in calls:
            if call["script"] == "main" and "--work-dir" in call["argv"]:
                wd = call["argv"][call["argv"].index("--work-dir") + 1]
                shutil.rmtree(wd, ignore_errors=True)
        return proc, calls

    def _main_argv(self, calls):
        mains = [c["argv"] for c in calls if c["script"] == "main"]
        self.assertEqual(len(mains), 1, calls)
        return mains[0]

    def _opt(self, argv, flag):
        self.assertIn(flag, argv)
        return argv[argv.index(flag) + 1]

    # -- scenarios -------------------------------------------------------

    def test_shells_available(self) -> None:
        self.assertIn("bash", self.SHELLS)

    def test_a_arguments_unset_preset_agent_uses_default_org(self) -> None:
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(shell, {"ARG_AGENT": "Support_Agent"})
                self.assertEqual(proc.returncode, 0, proc.stderr)
                argv = self._main_argv(calls)
                self.assertEqual(self._opt(argv, "--org-alias"), "default-org")
                self.assertEqual(self._opt(argv, "--agent"), "Support_Agent")
                self.assertTrue(proc.stdout.rstrip().endswith("=== RESULT ==="))

    def test_b_flags_in_arguments(self) -> None:
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(
                    shell, {"ARGUMENTS": "--org o1 --agent a1 --version=v3 --force"}
                )
                self.assertEqual(proc.returncode, 0, proc.stderr)
                argv = self._main_argv(calls)
                self.assertEqual(self._opt(argv, "--org-alias"), "o1")
                self.assertEqual(self._opt(argv, "--agent"), "a1")
                self.assertEqual(self._opt(argv, "--version"), "v3")
                self.assertIn("--force", argv)

    def test_c_flags_override_preset_env(self) -> None:
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(shell, {
                    "ARGUMENTS": "document * the agent --org=o2 --agent a2",
                    "ARG_ORG": "env-org",
                    "ARG_AGENT": "EnvAgent",
                })
                self.assertEqual(proc.returncode, 0, proc.stderr)
                argv = self._main_argv(calls)
                self.assertEqual(self._opt(argv, "--org-alias"), "o2")
                self.assertEqual(self._opt(argv, "--agent"), "a2")

    def test_preset_org_skips_default_lookup(self) -> None:
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(shell, {
                    "ARG_ORG": "env-org", "ARG_AGENT": "EnvAgent",
                    "SF_STUB_MODE": "fail",
                })
                self.assertEqual(proc.returncode, 0, proc.stderr)
                argv = self._main_argv(calls)
                self.assertEqual(self._opt(argv, "--org-alias"), "env-org")

    def test_d_nothing_resolvable_prints_usage(self) -> None:
        cases = [
            ("unset", {"SF_STUB_MODE": "unset"}, True),
            ("sf-fails", {"SF_STUB_MODE": "fail"}, True),
            ("no-sf", {}, False),
            ("agent-only-no-default", {"SF_STUB_MODE": "unset", "ARG_AGENT": "A"}, True),
        ]
        for shell in self.SHELLS:
            for label, env, with_sf in cases:
                with self.subTest(shell=shell, case=label):
                    proc, calls = self._run(shell, env, with_sf=with_sf)
                    self.assertNotEqual(proc.returncode, 0)
                    self.assertIn("Which agent should I document", proc.stderr)
                    self.assertEqual(
                        [c for c in calls if c["script"] == "main"], []
                    )

    # -- SKILL_ROOT discovery: ADK eval artifacts/ staging layout ----------

    def _assert_all_from(self, calls, scripts_dir: Path) -> None:
        """main, emit_result and fs_guard all ran from ``scripts_dir``."""
        real = scripts_dir.resolve()
        self.assertEqual({c["script"] for c in calls}, {"main", "emit", "fs_guard"})
        for call in calls:
            self.assertTrue(
                Path(call["path"]).is_relative_to(real), (call["path"], real)
            )

    def test_e_scripts_only_under_artifacts_of_exported_root(self) -> None:
        staged = self.tmp / "staged" / _SKILL_NAME
        scripts = self._make_stub_scripts(staged / "artifacts")
        (staged / "SKILL.md").write_text("# staged\n")
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(
                    shell, {"ARG_AGENT": "A", "ARG_ORG": "o"},
                    skill_root=str(staged),
                )
                self.assertEqual(proc.returncode, 0, proc.stderr)
                self._assert_all_from(calls, scripts)
                self._main_argv(calls)

    def test_f_artifacts_found_via_install_root_probe(self) -> None:
        # SKILL_ROOT unset: the candidate comes from the $HOME/.claude/skills probe.
        staged = self.home / ".claude" / "skills" / _SKILL_NAME
        scripts = self._make_stub_scripts(staged / "artifacts")
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(
                    shell, {"ARG_AGENT": "A", "ARG_ORG": "o"}, skill_root="",
                )
                self.assertEqual(proc.returncode, 0, proc.stderr)
                self._assert_all_from(calls, scripts)

    def test_g_candidate_root_preferred_over_its_artifacts(self) -> None:
        root_scripts = self.root / "scripts"
        self._make_stub_scripts(self.root / "artifacts")
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(shell, {"ARG_AGENT": "A", "ARG_ORG": "o"})
                self.assertEqual(proc.returncode, 0, proc.stderr)
                self._assert_all_from(calls, root_scripts)

    def test_h_earlier_candidate_artifacts_beats_later_candidate_root(self) -> None:
        # Candidate order is unchanged: exported SKILL_ROOT (artifacts layout)
        # wins over a later install root that has scripts/ at its top level.
        staged = self.tmp / "staged" / _SKILL_NAME
        scripts = self._make_stub_scripts(staged / "artifacts")
        self._make_stub_scripts(self.home / ".claude" / "skills" / _SKILL_NAME)
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(
                    shell, {"ARG_AGENT": "A", "ARG_ORG": "o"},
                    skill_root=str(staged),
                )
                self.assertEqual(proc.returncode, 0, proc.stderr)
                self._assert_all_from(calls, scripts)

    def test_i_no_scripts_anywhere_reports_guard_message(self) -> None:
        empty = self.tmp / "empty" / _SKILL_NAME
        (empty / "artifacts").mkdir(parents=True)
        for shell in self.SHELLS:
            with self.subTest(shell=shell):
                proc, calls = self._run(
                    shell, {"ARG_AGENT": "A", "ARG_ORG": "o"},
                    skill_root=str(empty),
                )
                self.assertEqual(proc.returncode, 1)
                self.assertIn(f"{_SKILL_NAME}: scripts not found", proc.stderr)
                self.assertEqual(calls, [])


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