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/_shared/paths.py
View on GitHub"""Canonical path helpers for investigating-agentforce-architecture.
Layout:
~/.vibe/data/investigating-agentforce-architecture/
└── <org_id_15>/
└── <agent_api_name>__<agent_version>/
├── <agent>_<ver>_metadata_tree.json ← rendered tree
└── .emit_ctx.json ← per-run shell ctx
Validation strategy
-------------------
The three "agent-identity" segments (org_id_15, agent_api_name, agent_version)
are validated by the regex helpers in the sibling ``fs_guard`` module. Any
segment containing ``..``, ``/``, or characters outside its regex charclass
raises ``PathValidationError`` — direct ``Path`` composition from unvalidated
input would be a path-traversal vulnerability and is prohibited.
Runtime override
----------------
``DATA_ROOT`` / ``CACHE_ROOT`` are resolved via the ``runtime`` module so
that entry scripts can override them via ``--data-dir`` / ``--cache-dir``
CLI flags. The default values (``~/.vibe/{data,cache}/...``)
are runtime-agnostic; AFV OOTB, Codex, Cursor, OpenCode each pass their
own override paths.
"""
from __future__ import annotations
from pathlib import Path
from . import fs_guard
from . import runtime
# -----------------------------------------------------------------------------
# Roots
# -----------------------------------------------------------------------------
DATA_ROOT: Path = runtime.resolve_data_root("investigating-agentforce-architecture")
CACHE_ROOT: Path = runtime.resolve_cache_root("investigating-agentforce-architecture")
class PathValidationError(ValueError):
"""Raised when a path segment fails validation.
Wraps fs_guard's ``ValidationError`` so callers have a single exception
type to catch.
"""
def __init__(self, label: str, reason: str) -> None:
self.label = label
self.reason = reason
super().__init__(f"{label}: {reason}")
# -----------------------------------------------------------------------------
# Validation helpers
# -----------------------------------------------------------------------------
def _validate_agent_triple(
org_id_15: str, agent_api_name: str, agent_version: str
) -> None:
"""Validate the three identity segments. Raises PathValidationError on
failure, wrapping fs_guard's ValidationError so callers don't need to
know about fs_guard internals."""
try:
fs_guard.validate_org_id_15(org_id_15, label="org_id_15")
fs_guard.validate_api_name(agent_api_name, label="agent_api_name")
fs_guard.validate_agent_version(agent_version, label="agent_version")
except fs_guard.ValidationError as e:
raise PathValidationError(e.label, e.reason) from e
# -----------------------------------------------------------------------------
# Path builders
# -----------------------------------------------------------------------------
def agent_dir(
org_id_15: str, agent_api_name: str, agent_version: str
) -> Path:
"""Return ``DATA_ROOT/<org_id_15>/<agent_api_name>__<agent_version>/``.
All three segments are regex-validated before being joined.
"""
_validate_agent_triple(org_id_15, agent_api_name, agent_version)
return DATA_ROOT / org_id_15 / f"{agent_api_name}__{agent_version}"
def architecture_tree_path(
org_id_15: str, agent_api_name: str, agent_version: str
) -> Path:
"""Return the path to the rendered metadata tree JSON.
Filename convention: ``<agent_api_name>_<agent_version>_metadata_tree.json``.
"""
base = agent_dir(org_id_15, agent_api_name, agent_version)
return base / f"{agent_api_name}_{agent_version}_metadata_tree.json"
def architecture_emit_ctx_path(
org_id_15: str, agent_api_name: str, agent_version: str
) -> Path:
"""Return the path to the per-run ``.emit_ctx.json``.
The file is dotfile-named to signal per-run shell state.
"""
base = agent_dir(org_id_15, agent_api_name, agent_version)
return base / ".emit_ctx.json"
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 |