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/metadata_listing.py

View on GitHub
"""Metadata API listMetadata wrappers — for sObjects that are NOT
exposed via SOQL on Tooling or Data API (e.g. GenAiPromptTemplate).

Wraps the sf CLI `sf org list metadata` recipe. Not a REST client call —
uses subprocess via sf_cli.run_sf. Failure semantics mirror the rest:
returns [] on known-missing + surfaces unresolved reasons upstream;
raises SfCliError / AuthRequired on unknown failures.
"""
from __future__ import annotations

import subprocess
import xml.etree.ElementTree as ET
import zipfile
from pathlib import Path
from typing import Any, Dict, List

from rest_client import redact_error
from sf_cli import (
    AuthRequired,
    _redact_subprocess_stderr,
    _stderr_matches_auth,
    run_sf,
)


# Metadata XML default namespace — same as parse_bundle.NS. Duplicated
# (rather than imported) to keep the "no intra-skill imports" convention
# documented throughout the pipeline.
_NS = {"sf": "http://soap.sforce.com/2006/04/metadata"}


def list_prompt_template_metadata(org_alias: str) -> List[Dict[str, str]]:
    """Return every GenAiPromptTemplate metadata component in the org.

    Each row has the shape produced by `sf org list metadata --json`:
      {"id": "0hfUv...", "fullName": "AGNT_...", "type": "GenAiPromptTemplate",
       "namespacePrefix": "...", ...}

    Empty list on success with no templates. Raises SfCliError on CLI
    failure (caller decides whether to treat as fatal).
    """
    data = run_sf("list_metadata_genaiprompttemplate", ORG_ALIAS=org_alias)
    result = data.get("result")
    if not isinstance(result, list):
        return []
    return [r for r in result if isinstance(r, dict)]


def _find_text(el: ET.Element | None, path: str) -> str | None:
    if el is None:
        return None
    found = el.find(path, _NS)
    if found is None:
        return None
    return found.text


def _parse_prompt_template_xml(xml_bytes: bytes) -> Dict[str, Any] | None:
    """Parse a single .genAiPromptTemplate XML file into a body dict.

    Returns None on parse failure so the caller can log + skip. The
    returned dict carries developerName/masterLabel/activeVersionIdentifier/
    content/inputs — absent optional fields become None or empty lists.

    Version selection: if multiple <templateVersions> elements exist,
    prefer the one whose `versionIdentifier` matches the template-level
    `activeVersionIdentifier`; otherwise fall back to the first version.
    """
    try:
        root = ET.fromstring(xml_bytes)
    except ET.ParseError:
        return None

    developer_name = _find_text(root, "sf:developerName")
    master_label = _find_text(root, "sf:masterLabel")
    active_version = _find_text(root, "sf:activeVersionIdentifier")

    versions = root.findall("sf:templateVersions", _NS)
    picked: ET.Element | None = None
    if versions:
        if active_version:
            for v in versions:
                vid = _find_text(v, "sf:versionIdentifier")
                if vid and vid == active_version:
                    picked = v
                    break
        if picked is None:
            picked = versions[0]

    content = _find_text(picked, "sf:content") if picked is not None else None

    inputs: List[Dict[str, str]] = []
    if picked is not None:
        for inp in picked.findall("sf:inputs", _NS):
            name = _find_text(inp, "sf:apiName") or _find_text(inp, "sf:name")
            data_type = _find_text(inp, "sf:dataType")
            if name is None and data_type is None:
                continue
            entry: Dict[str, str] = {}
            if name is not None:
                entry["name"] = name
            if data_type is not None:
                entry["dataType"] = data_type
            inputs.append(entry)

    return {
        "developerName": developer_name,
        "masterLabel": master_label,
        "activeVersionIdentifier": active_version,
        "content": content,
        "inputs": inputs,
    }


# Timeout for `sf project retrieve start` — matches the prior YAML recipe's
# `timeout_seconds: 300`. Kept as a module constant (rather than a literal
# at the call site) so future adjustments have a single home.
_RETRIEVE_TIMEOUT_SECONDS = 300

# stderr patterns that mean "the CLI ran but there is no authenticated org
# for this alias" — reraised as AuthRequired. Mirrors the prior recipe's
# `auth_required_stderr_patterns` field.
_RETRIEVE_AUTH_PATTERNS = ("NoOrgAuthenticationError", "AuthInfoError")


def _run_retrieve(argv: List[str], timeout: int) -> "subprocess.CompletedProcess[str]":
    """Thin wrapper over `subprocess.run` for the retrieve-start call.

    Exists so tests can mock the subprocess boundary without also mocking
    the argv-construction logic — see `RetrievePromptTemplatesTests`.
    """
    return subprocess.run(
        argv,
        capture_output=True,
        text=True,
        timeout=timeout,
        check=False,
    )


def retrieve_prompt_templates(
    org_alias: str,
    template_names: List[str],
    work_dir: Path,
) -> Dict[str, Dict[str, Any]]:
    """Retrieve GenAiPromptTemplate bodies via `sf project retrieve start`.

    The sf plugin's `--metadata` flag is REPEATED once per requested
    template (`--metadata GenAiPromptTemplate:A --metadata
    GenAiPromptTemplate:B ...`). A comma-joined value is NOT a valid list;
    the CLI treats the whole comma-joined string as a single malformed
    member name, silently skips it, and the resulting zip contains only
    `package.xml` (observed 2026-05-05 against my-org-alias). Hence we
    bypass the YAML recipe loader here — `run_sf` substitutes
    `{{METADATA_SPEC}}` single-shot and has no list-expansion primitive.

    The resulting `unpackaged.zip` carries one `.genAiPromptTemplate` XML
    file per template under `unpackaged/genAiPromptTemplates/`.

    Returns a dict keyed by `developerName`. Templates the retrieve
    didn't produce a file for are OMITTED (caller handles missing by
    leaving them in `_pending_fetches`).

    Failure modes:
      - Empty `template_names` → short-circuits with `{}` and no sf call.
      - `AuthRequired` (stderr matches auth patterns) → re-raised.
      - `SfCliError` (any other non-zero exit, timeout, etc) → swallowed;
        returns `{}`. Caller logs the retrieval-failure reason at the
        call site.
      - Zip missing or malformed → returns `{}`.
      - XML parse failure on a specific file → that file is skipped; the
        other templates in the same zip still parse and return.
    """
    if not template_names:
        return {}

    retrieve_dir = work_dir / "prompt_template_retrieve"
    retrieve_dir.mkdir(parents=True, exist_ok=True)
    # Nuke stale files from a prior invocation so we don't trust an old
    # unpackaged.zip if this run's sf call fails before writing one.
    for path in retrieve_dir.iterdir():
        if path.is_file():
            path.unlink()
        elif path.is_dir():
            _rm_tree(path)

    argv: List[str] = [
        "sf",
        "project",
        "retrieve",
        "start",
        "--target-org",
        org_alias,
        "--target-metadata-dir",
        str(retrieve_dir),
        "--json",
    ]
    for name in template_names:
        argv.extend(["--metadata", f"GenAiPromptTemplate:{name}"])

    try:
        cp = _run_retrieve(argv, _RETRIEVE_TIMEOUT_SECONDS)
    except subprocess.TimeoutExpired as e:
        # timeout exceptions may carry stderr; route through
        # redact_error before surfacing — then swallow as non-fatal, same
        # contract the old run_sf-based path had for SfCliError.
        _ = redact_error(e)
        return {}
    except (OSError, subprocess.SubprocessError) as e:
        _ = redact_error(e)
        return {}

    if cp.returncode != 0:
        # Classify: auth failure re-raises, everything else is non-fatal.
        if _stderr_matches_auth(cp.stderr, _RETRIEVE_AUTH_PATTERNS):
            safe_stderr = _redact_subprocess_stderr(cp.stderr)
            raise AuthRequired(safe_stderr or "auth required")
        return {}

    zip_path = retrieve_dir / "unpackaged.zip"
    if not zip_path.exists():
        return {}

    results: Dict[str, Dict[str, Any]] = {}
    try:
        with zipfile.ZipFile(zip_path) as zf:
            for info in zf.infolist():
                name = info.filename
                if not name.endswith(".genAiPromptTemplate"):
                    continue
                if "genAiPromptTemplates/" not in name:
                    continue
                try:
                    xml_bytes = zf.read(info)
                except (KeyError, zipfile.BadZipFile):
                    continue
                body = _parse_prompt_template_xml(xml_bytes)
                if not body:
                    continue
                dev_name = body.get("developerName")
                if not dev_name:
                    # Fall back to the file stem if the XML somehow lacks
                    # a <developerName> element — keeps the caller's
                    # lookup working.
                    stem = Path(name).stem
                    if stem:
                        body["developerName"] = stem
                        dev_name = stem
                if dev_name:
                    results[dev_name] = body
    except zipfile.BadZipFile:
        return {}

    return results


def _rm_tree(path: Path) -> None:
    """Recursively delete a directory tree. stdlib-only, no shutil import
    at module top to keep the import surface minimal."""
    for child in path.iterdir():
        if child.is_dir():
            _rm_tree(child)
        else:
            child.unlink()
    path.rmdir()
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