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

references/contract.json

View on GitHub
{
  "_doc": "retired-name references replaced with plugin-scoped layout. Machine-readable I/O contract for agentforce-architecture-analyze. Orchestrator code reads this file (not SKILL.md prose) to discover the input schema, output keys, STATUS enum, and error-contract rules. The architecture skill runs inline (no subagent).",
  "_schema_version": "3.1",
  "_schema_notes": "3.1 (2026-05-05) canonicalizes `invocation_type` on STANDARD_ACTION / UNKNOWN nodes in the metadata tree. Prior versions split this across `raw_invocation_type` (bundle-sourced nodes) and `raw_action_type` (flow-actionCall-sourced nodes). Both legacy keys are still tolerated by readers for one release.",
  "input": {
    "required": {
      "org_alias": {
        "type": "string",
        "description": "sf CLI alias (e.g. 'my-org-alias'). Auth is always derived via `sf org display --target-org $ORG_ALIAS --json` (instance URL) and `sf org auth show-access-token --target-org $ORG_ALIAS --json --no-prompt` (access token)."
      },
      "agent_api_name": {
        "type": "string",
        "regex": "^[A-Za-z0-9_]+$",
        "description": "BotDefinition.DeveloperName (e.g. 'MyAgent'). Must match the regex above; INVALID_INPUT otherwise."
      }
    },
    "optional": {
      "agent_version_api_name": {
        "type": "string",
        "description": "BotVersion.DeveloperName (e.g. 'v5'). When omitted, the agent auto-picks the Active version with the highest natural-key sort (v10 > v9); VERSION_AUTO_PICKED=true in the RESULT block."
      },
      "org_id_15": {
        "type": "string",
        "regex": "^[A-Za-z0-9]{15}$",
        "description": "15-char org ID. If omitted, derived from `sf org display`."
      },
      "org_id_18": {
        "type": "string",
        "regex": "^[A-Za-z0-9]{18}$",
        "description": "18-char org ID. If omitted, derived from `sf org display`."
      },
      "session_id": {
        "type": "string",
        "description": "Only used to name the ephemeral $WORK_DIR. Random UUID if omitted."
      },
      "work_dir": {
        "type": "absolute_path",
        "description": "Ephemeral scratch. Default: /tmp/agentforce-architecture-analyze-<epoch>-<rand>."
      },
      "cache_root": {
        "type": "absolute_path",
        "description": "Internal rebuildable cache root. Default: ~/.vibe/cache/agentforce-architecture-analyze. Override with --cache-dir <path>."
      },
      "data_root": {
        "type": "absolute_path",
        "description": "Durable user-facing output root. Default: ~/.vibe/data/agentforce-architecture-analyze. Override with --data-dir <path>."
      },
      "force_refresh": {
        "type": "boolean",
        "description": "If true, ignore cache and rewrite. Default: false."
      }
    },
    "minimum_viable": {
      "org_alias": "my-org-alias",
      "agent_api_name": "MyAgent"
    },
    "notes": [
      "Standalone and orchestrated modes accept the same input fields; no renames.",
      "To bypass cache, delete the cache entry or pass force_refresh: true."
    ]
  },
  "output": {
    "format": "Two-part return message: (1) one-line prose status, (2) blank line, (3) === RESULT === key-value block. The KV block is always LAST in the output and always present.",
    "parse_rule": "Find the line '=== RESULT ===', then read subsequent lines as KEY=VALUE pairs until EOF. Values are raw strings; no quoting; one pair per line.",
    "parse_examples": {
      "bash": "awk -F= '/^STATUS=/{print $2; exit}' <<< \"$subagent_output\"",
      "python": "import re; dict(line.split('=', 1) for line in output.splitlines() if re.match(r'^[A-Z_]+=', line))"
    },
    "keys": {
      "STATUS": {
        "type": "enum",
        "presence": "always",
        "description": "Terminal status. See error_contract for per-status required keys.",
        "values": [
          "OK",
          "PARTIAL_OK",
          "INVALID_INPUT",
          "AUTH_REQUIRED",
          "AGENT_NOT_FOUND",
          "AGENT_VERSION_NOT_FOUND",
          "RETRIEVE_FAILED",
          "WRITE_FAILED"
        ]
      },
      "ERROR_DETAIL": {
        "type": "string",
        "presence": "on_error",
        "description": "Human-readable explanation on any non-OK STATUS. Sanitized (no backticks/quotes/dollar signs/newlines)."
      },
      "AGENT_API_NAME": {
        "type": "string",
        "presence": "always",
        "description": "Echo of input agent_api_name. May be empty on INVALID_INPUT if sanitize rejected before resolution."
      },
      "AGENT_VERSION": {
        "type": "string",
        "presence": "on_success_or_after_resolve",
        "description": "Resolved BotVersion.DeveloperName (e.g. 'v5')."
      },
      "VERSION_AUTO_PICKED": {
        "type": "boolean",
        "presence": "on_success_or_after_resolve",
        "description": "True iff agent_version_api_name was omitted and the agent auto-picked."
      },
      "AGENT_GENERATION": {
        "type": "enum",
        "presence": "always",
        "values": ["classic", "nga", "unknown"],
        "description": "classic = AiCopilot__ planner, nga = Atlas__ planner, unknown = anything else / not resolved."
      },
      "BOT_ID": {
        "type": "string",
        "presence": "on_success_or_after_resolve",
        "description": "18-char BotDefinition.Id from SOQL."
      },
      "ORG_ID_15": {
        "type": "string",
        "presence": "on_success_or_after_auth",
        "description": "15-char org ID. Cache-key prefix."
      },
      "ORG_ID_18": {
        "type": "string",
        "presence": "on_success_or_after_auth",
        "description": "18-char org ID (from `sf org display`)."
      },
      "OUTPUT_JSON_PATH": {
        "type": "absolute_path",
        "presence": "on_success",
        "description": "Durable {agent}_{version}_metadata_tree.json path under the resolved data_root."
      },
      "OUTPUT_SUMMARY_PATH": {
        "type": "absolute_path",
        "presence": "always_empty",
        "description": "Reserved — historically pointed at {agent}_{version}_metadata_tree.summary.md. Dropped in ; field is now always emitted empty for RESULT-block shape stability."
      },
      "CACHE_PATH": {
        "type": "absolute_path",
        "presence": "on_success_or_after_cache_check",
        "description": "Cache dir ($CACHE_ROOT/$ORG_ID_15/$AGENT__$VERSION/). Ends with /."
      },
      "CACHE_HIT": {
        "type": "boolean",
        "presence": "on_success_or_after_cache_check",
        "description": "True iff the cache was served without any Metadata API retrieves."
      },
      "CACHED_AT_UTC": {
        "type": "iso8601_utc_or_empty",
        "presence": "on_success_or_after_cache_check",
        "description": "ISO-8601 UTC built-at time. On cache hit this is the age of the cached snapshot; on cold build this is the just-computed timestamp."
      },
      "NODE_COUNT": {
        "type": "integer",
        "presence": "on_success",
        "description": "Total nodes in the declared_action_tree."
      },
      "DEPTH": {
        "type": "integer",
        "presence": "on_success",
        "description": "Max depth of the tree (BOT_DEFINITION = depth 0)."
      },
      "PARTIAL": {
        "type": "boolean",
        "presence": "on_success",
        "description": "True iff the tree is incomplete (planner unresolved OR MAX_WAVE hit). When true, STATUS=PARTIAL_OK."
      },
      "UNRESOLVED_COUNT": {
        "type": "integer",
        "presence": "on_success",
        "description": "Length of tree._unresolved[]."
      },
      "AVAILABLE_BOTS": {
        "type": "csv",
        "presence": "on_AGENT_NOT_FOUND",
        "description": "Comma-separated list of all BotDefinition.DeveloperName values in the org."
      },
      "AVAILABLE_VERSIONS": {
        "type": "csv",
        "presence": "on_AGENT_VERSION_NOT_FOUND",
        "description": "Format: 'v5(Active),v4(Inactive),...' — natural-key sorted DESC."
      },
      "RESULT_BLOCK_PATH": {
        "type": "absolute_path",
        "presence": "always",
        "description": "Path to $DATA_DIR/last_result_block.txt — byte-for-byte tee written BEFORE stdout."
      },
      "WALL_TIME_SECONDS": {
        "type": "float",
        "presence": "always",
        "description": "End-to-end wall-clock seconds. Two decimals. Target: 90-220s cold, <2s warm."
      }
    }
  },
  "error_contract": {
    "OK": {
      "description": "Tree built, zero unresolved, planner resolved.",
      "required_keys": ["STATUS", "AGENT_API_NAME", "AGENT_VERSION", "VERSION_AUTO_PICKED", "AGENT_GENERATION", "BOT_ID", "ORG_ID_15", "ORG_ID_18", "OUTPUT_JSON_PATH", "OUTPUT_SUMMARY_PATH", "CACHE_PATH", "CACHE_HIT", "CACHED_AT_UTC", "NODE_COUNT", "DEPTH", "PARTIAL", "UNRESOLVED_COUNT", "RESULT_BLOCK_PATH", "WALL_TIME_SECONDS"],
      "optional_keys": []
    },
    "PARTIAL_OK": {
      "description": "Tree built but planner unresolved (Bot.bot had no planner) OR waves hit MAX_WAVE=5. tree._unresolved[] explains.",
      "required_keys": ["STATUS", "AGENT_API_NAME", "AGENT_VERSION", "AGENT_GENERATION", "BOT_ID", "ORG_ID_15", "ORG_ID_18", "OUTPUT_JSON_PATH", "CACHE_PATH", "PARTIAL", "UNRESOLVED_COUNT", "WALL_TIME_SECONDS", "RESULT_BLOCK_PATH"],
      "optional_keys": ["OUTPUT_SUMMARY_PATH", "CACHE_HIT", "CACHED_AT_UTC", "NODE_COUNT", "DEPTH", "VERSION_AUTO_PICKED", "ERROR_DETAIL"]
    },
    "INVALID_INPUT": {
      "description": "agent_api_name failed [A-Za-z0-9_]+ regex, or other input validation (org_alias empty, ORG_ID_15 regex, $WORK_DIR symlink/foreign-owned).",
      "required_keys": ["STATUS", "ERROR_DETAIL", "AGENT_API_NAME"],
      "optional_keys": ["ORG_ID_15", "ORG_ID_18"]
    },
    "AUTH_REQUIRED": {
      "description": "`sf org display` returned nothing, or a SOQL/Metadata call failed with an auth error. Caller must run `sf org login web --alias $ORG_ALIAS`.",
      "required_keys": ["STATUS", "ERROR_DETAIL", "AGENT_API_NAME"],
      "optional_keys": ["ORG_ID_15", "ORG_ID_18"]
    },
    "AGENT_NOT_FOUND": {
      "description": "BotDefinition.DeveloperName not in the org. AVAILABLE_BOTS carries the CSV of what IS in the org.",
      "required_keys": ["STATUS", "ERROR_DETAIL", "AGENT_API_NAME", "AVAILABLE_BOTS"],
      "optional_keys": ["ORG_ID_15", "ORG_ID_18"]
    },
    "AGENT_VERSION_NOT_FOUND": {
      "description": "No matching BotVersion under the bot (explicit version doesn't exist, or no Active version found during auto-pick).",
      "required_keys": ["STATUS", "ERROR_DETAIL", "AGENT_API_NAME", "AVAILABLE_VERSIONS"],
      "optional_keys": ["BOT_ID", "ORG_ID_15", "ORG_ID_18"]
    },
    "RETRIEVE_FAILED": {
      "description": "`sf project retrieve start` failed (network, permissions, zip unreadable). ERROR_DETAIL carries the specifics.",
      "required_keys": ["STATUS", "ERROR_DETAIL", "AGENT_API_NAME", "AGENT_VERSION", "BOT_ID"],
      "optional_keys": ["ORG_ID_15", "ORG_ID_18", "OUTPUT_JSON_PATH"]
    },
    "WRITE_FAILED": {
      "description": "Filesystem write failed during finalize (DATA_DIR rename, CACHE_DIR rename, or tree rewrite).",
      "required_keys": ["STATUS", "ERROR_DETAIL", "AGENT_API_NAME", "AGENT_VERSION"],
      "optional_keys": ["BOT_ID", "ORG_ID_15", "ORG_ID_18", "CACHE_HIT", "CACHED_AT_UTC"]
    }
  },
  "stability": {
    "key_names": "Stable. Key-name changes require a NOTICE.md entry and a skill reinstall; consumers read this contract to discover the current key set.",
    "error_codes": "The STATUS enum is fixed at 8 values. A new status is a breaking change for consumers that switch on STATUS.",
    "path_format": "All path values are absolute (no tilde expansion required). One KEY=VALUE per line. No trailing whitespace.",
    "order": "Keys inside the RESULT block appear in a stable order — orchestrators should not depend on order but may use it for human readability."
  },
  "referenced_files": {
    "skill_md": "<SKILL_ROOT>/SKILL.md"
  }
}
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