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

View on GitHub
#!/usr/bin/env python3
"""Final-phase RESULT emitter for investigating-agentforce-architecture.

Reads `$WORK_DIR/.emit_ctx.json` (populated by write_emit_ctx.py) and prints
the final output:

    1. One-line prose status (for humans; first signal in the log).
    2. A blank line.
    3. The `=== RESULT ===` KV block.

BEFORE writing to stdout, the complete RESULT block is teed to
`$DATA_DIR/last_result_block.txt`. Writing the tee first means a consumer
reading the file can never see a truncated block — disk write is atomic
(`tmp + os.replace`), and the stdout print is a best-effort afterthought.

The callers that abort early (AGENT_NOT_FOUND, AGENT_VERSION_NOT_FOUND,
INVALID_INPUT) emit their own RESULT blocks directly — resolve_bot.py and
fs_guard.py have the same disk-tee discipline. All other terminal paths
(OK, PARTIAL_OK, AUTH_REQUIRED, RETRIEVE_FAILED, WRITE_FAILED) flow through
this script.

Usage:
    python3 emit_result.py

Inputs:
    env $WORK_DIR     reads $WORK_DIR/.emit_ctx.json

Outputs:
    $DATA_DIR/last_result_block.txt    full RESULT block (atomic write)
    stdout                             prose line + RESULT block
    exit 0                             always (this script emits; the bash
                                       harness decides the agent's exit code)
    exit 1                             missing env, missing ctx file, bad JSON
"""
import json
import os
import pathlib
import sys
import time

STATUS_ENUM = {
    "OK",
    "PARTIAL_OK",
    "INVALID_INPUT",
    "AUTH_REQUIRED",
    "AGENT_NOT_FOUND",
    "AGENT_VERSION_NOT_FOUND",
    "RETRIEVE_FAILED",
    "WRITE_FAILED",
}

PROSE = {
    "OK": "Declared action tree discovered and cached.",
    "PARTIAL_OK": "Declared action tree partially discovered — see UNRESOLVED_COUNT.",
    "INVALID_INPUT": "Input validation failed.",
    "AUTH_REQUIRED": "sf CLI not authenticated for this org.",
    "AGENT_NOT_FOUND": "BotDefinition.DeveloperName not found in the org.",
    "AGENT_VERSION_NOT_FOUND": "No matching BotVersion under the bot.",
    "RETRIEVE_FAILED": "Metadata API retrieve failed (auth/network/permissions).",
    "WRITE_FAILED": "A filesystem write failed during finalize.",
}


def scrub(s) -> str:
    if not isinstance(s, str):
        s = "" if s is None else str(s)
    bad = set("`$\"\\\r\t\0\n")
    return "".join(c for c in s if c not in bad)


def bool_str(v) -> str:
    if isinstance(v, bool):
        return "true" if v else "false"
    s = str(v).lower()
    return "true" if s in ("true", "1", "yes", "on") else "false"


def build_block(ctx: dict, wall_time_seconds: float) -> str:
    status = (ctx.get("status") or "").strip().upper()
    if status not in STATUS_ENUM:
        status = "WRITE_FAILED"

    lines = ["=== RESULT ===", f"STATUS={status}"]

    error_detail = scrub(ctx.get("error_detail", ""))
    if error_detail:
        lines.append(f"ERROR_DETAIL={error_detail}")

    # Always-emitted identity fields (may be empty on early-abort paths)
    lines.extend([
        f"AGENT_API_NAME={scrub(ctx.get('agent_api_name', ''))}",
        f"AGENT_VERSION={scrub(ctx.get('agent_version', ''))}",
        f"VERSION_AUTO_PICKED={bool_str(ctx.get('version_auto_picked', False))}",
        f"AGENT_GENERATION={scrub(ctx.get('agent_generation', '') or 'unknown')}",
        f"BOT_ID={scrub(ctx.get('bot_id', ''))}",
        f"ORG_ID_15={scrub(ctx.get('org_id_15', ''))}",
        f"ORG_ID_18={scrub(ctx.get('org_id_18', ''))}",
    ])

    # Output + cache paths (populated on success; may be empty on fail paths)
    # OUTPUT_ARCHITECTURE_PATH is always emitted — empty
    # string on fail paths, cache-hit paths where the renderer wasn't
    # invoked, or when render failed. Downstream consumers can distinguish
    # "no architecture produced" from "architecture produced but stale"
    # by cross-referencing RENDER_FAILED + CACHE_HIT.
    lines.extend([
        f"OUTPUT_JSON_PATH={scrub(ctx.get('output_json_path', ''))}",
        f"OUTPUT_SUMMARY_PATH={scrub(ctx.get('output_summary_path', ''))}",
        f"OUTPUT_ARCHITECTURE_PATH={scrub(ctx.get('architecture_path', '') or '')}",
        f"CACHE_PATH={scrub(ctx.get('cache_path', ''))}",
        f"CACHE_HIT={bool_str(ctx.get('cache_hit', False))}",
        f"CACHED_AT_UTC={scrub(ctx.get('cached_at_utc', ''))}",
    ])

    # Tree stats
    # emit `_partial_reason` + a rollup of `_pending_fetches` counts
    # alongside the existing PARTIAL / UNRESOLVED_COUNT fields. The write
    # path populates ctx["partial"], ctx["partial_reason"], and
    # ctx["pending_fetches_count"] from the finalized tree JSON —
    # emit_result is intentionally presentation-only and does not re-read
    # the tree itself (ctx is the single source of truth per the emit
    # contract).
    partial_flag = bool(ctx.get("partial", False))
    partial_reason = scrub(ctx.get("partial_reason", "") or "")
    pending_fetches_count = int(ctx.get("pending_fetches_count", 0) or 0)

    # If the upstream pipeline forgot to populate partial_reason but
    # flagged partial=True, emit an empty value rather than nothing —
    # downstream consumers can distinguish "no reason supplied" from
    # "key missing" this way.
    lines.extend([
        f"NODE_COUNT={int(ctx.get('node_count', 0) or 0)}",
        f"DEPTH={int(ctx.get('depth', 0) or 0)}",
        f"PARTIAL={bool_str(partial_flag)}",
        f"PARTIAL_REASON={partial_reason}",
        f"PENDING_FETCHES_COUNT={pending_fetches_count}",
        f"UNRESOLVED_COUNT={int(ctx.get('unresolved_count', 0) or 0)}",
    ])

    # when the tree is partial but status was left blank / "OK",
    # auto-promote the status to PARTIAL_OK so the RESULT block reflects
    # the tree's actual state. ERROR paths (AUTH_REQUIRED etc.) keep
    # their original status — never clobber a failure status.
    if partial_flag and status == "OK":
        # positional safety — `lines[1]` is by construction
        # "STATUS=...". If a future refactor reorders the header we want
        # a loud failure here rather than silently rewriting the wrong
        # line. Assertion cost is negligible; the payoff is catching a
        # whole class of refactor bugs at test time.
        assert lines[1].startswith("STATUS="), (
            f"emit block reordered — lines[1]={lines[1]!r}"
        )
        lines[1] = "STATUS=PARTIAL_OK"
        status = "PARTIAL_OK"

    # emit RENDER_FAILED unconditionally, and auto-promote to
    # PARTIAL_OK when the tree succeeded but the architecture.md render
    # raised. The signal surface is:
    # * RENDER_FAILED=true|false — always emitted.
    # * RENDER_ERROR_DETAIL=<...> — emitted ONLY on true, redacted
    # at write_emit_ctx-time.
    # * STATUS auto-promoted OK -> PARTIAL_OK; _partial_reason pinned
    # to "render-failed" when the tree wasn't already partial.
    # ERROR paths (AUTH_REQUIRED etc.) retain their original status:
    # render never runs in those cases, and render_failed defaults to
    # False so the auto-promote below is a no-op.
    render_failed = bool(ctx.get("render_failed", False))
    lines.append(f"RENDER_FAILED={bool_str(render_failed)}")
    if render_failed:
        detail = scrub(ctx.get("render_error_detail", "") or "")
        lines.append(f"RENDER_ERROR_DETAIL={detail}")
        if status == "OK":
            # Same positional-safety discipline as the partial auto-promote.
            assert lines[1].startswith("STATUS="), (
                f"emit block reordered — lines[1]={lines[1]!r}"
            )
            lines[1] = "STATUS=PARTIAL_OK"
            status = "PARTIAL_OK"
            # Pin a partial_reason so triagers can tell this apart from a
            # tree-level partial. We walk backwards to find the existing
            # PARTIAL_REASON line (always present — emitted above) and
            # rewrite in place. A fresh line would create two competing
            # reason values in the block.
            for idx in range(len(lines) - 1, -1, -1):
                if lines[idx].startswith("PARTIAL_REASON="):
                    # Only overwrite when the tree didn't already claim
                    # a reason — the tree's reason is more informative.
                    if lines[idx] == "PARTIAL_REASON=":
                        lines[idx] = "PARTIAL_REASON=render-failed"
                    break

    # Error-path-specific optional keys
    if status == "AGENT_NOT_FOUND":
        bots = scrub(ctx.get("available_bots", ""))
        if bots:
            lines.append(f"AVAILABLE_BOTS={bots}")
    if status == "AGENT_VERSION_NOT_FOUND":
        vers = scrub(ctx.get("available_versions", ""))
        if vers:
            lines.append(f"AVAILABLE_VERSIONS={vers}")

    lines.append(f"WALL_TIME_SECONDS={wall_time_seconds:.2f}")
    return "\n".join(lines) + "\n"


def main() -> int:
    work_dir_s = os.environ.get("WORK_DIR", "")
    if not work_dir_s:
        sys.stderr.write("emit_result.py: $WORK_DIR not set\n")
        return 1

    ctx_path = pathlib.Path(work_dir_s) / ".emit_ctx.json"
    try:
        ctx = json.loads(ctx_path.read_text())
    except FileNotFoundError:
        sys.stderr.write(f"emit_result.py: missing {ctx_path}\n")
        return 1
    except (OSError, json.JSONDecodeError) as e:
        sys.stderr.write(f"emit_result.py: cannot read {ctx_path}: {e}\n")
        return 1

    start_epoch = float(ctx.get("start_epoch") or time.time())
    wall = max(0.0, time.time() - start_epoch)

    data_dir_s = scrub(ctx.get("data_dir", ""))
    if not data_dir_s:
        # Fallback default — runtime-agnostic. Mirrors runtime.resolve_data_root()
        # in scripts/_shared/runtime.py (the pipeline's canonical helper). This
        # tool runs standalone (no sys.path to scripts/), so we duplicate the
        # default rather than import. If main.py ran with --data-dir, the
        # ctx.data_dir field already carries the override value, so this
        # branch is only reached when the pipeline aborted before writing it.
        data_dir_s = str(
            pathlib.Path.home()
            / ".vibe"
            / "data"
            / "investigating-agentforce-architecture"
            / "_agents"
        )
    data_dir = pathlib.Path(data_dir_s)
    tee_path = data_dir / "last_result_block.txt"

    body = build_block(ctx, wall)
    body += f"RESULT_BLOCK_PATH={tee_path}\n"

    try:
        data_dir.mkdir(parents=True, exist_ok=True)
        tmp = tee_path.with_suffix(tee_path.suffix + ".tmp")
        tmp.write_text(body)
        os.replace(tmp, tee_path)
    except OSError as e:
        sys.stderr.write(f"emit_result.py: tee failed ({e}); continuing with stdout\n")

    status = (ctx.get("status") or "").strip().upper()
    prose = PROSE.get(status, f"Unknown status {status}.")
    sys.stdout.write(prose + "\n\n")
    sys.stdout.write(body)
    return 0


if __name__ == "__main__":
    sys.exit(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