Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-generate

agentforce-generate

Flagged

Build, modify, audit, repair, optimize, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, reviews, or changes .agent files or aiAuthoringBundle metadata; asks to fix AgentScript, audit an existing agent, run an AgentScript health check, common-pitfall review, or baseline-versus-candidate repair loop; changes a response, action, subagent, route, state flow, or Agent Spec; migrates or upgrades a legacy GenAiPlannerBundle Agentforce agent (NOT an Einstein Bot) to an aiAuthoringBundle (Agent Script) agent; previews, debugs, deploys, publishes, or tests agents; uses sf agent generate/preview/publish/test; or manages Agentforce MCP servers, tools, assets, or authentication. DO NOT TRIGGER when: Apex, Flow, Prompt Template, Experience Cloud, or general Salesforce CLI work is unrelated to Agent Script; the source is an Einstein Bot (BotDefinition/BotVersion) — use agentforce-bot-upgrade; or the primary input is a production session or trace ID rather than an agent artifact.

FileKindSize
README.mdmarkdown5.4 KB
SKILL.mdskill md31.7 KB
assets/agent-spec-template.mdmarkdown6.4 KB
assets/agents/README.mdmarkdown2.6 KB
assets/agents/hello-world.agentother1.9 KB
assets/agents/knowledge-grounded.agentother5.6 KB
assets/agents/local-info-agent-annotated.agentother17.0 KB
assets/agents/order-service.agentother11.7 KB
assets/agents/production-faq.agentother3.9 KB
assets/agents/production-faq.bundle-meta.xmlconfig161 B
assets/agents/router-first.agentother5.6 KB
assets/agents/simple-qa.agentother1.9 KB
assets/agents/template-multi-subagent.agentother5.4 KB
assets/agents/template-single-subagent.agentother2.6 KB
assets/agents/verification-gate.agentother10.7 KB
assets/agents/voice-knowledge-grounded.agentother8.2 KB
assets/agents/voice-service-agent.agentother4.6 KB
assets/bundle-meta.xmlconfig808 B
assets/invocable-apex-template.clsother6.9 KB
assets/patterns/README.mdmarkdown10.8 KB
assets/patterns/action-callbacks.agentother4.7 KB
assets/patterns/advanced-input-bindings.agentother6.9 KB
assets/patterns/bidirectional-routing.agentother5.6 KB
assets/patterns/critical-input-collection.agentother12.2 KB
assets/patterns/delegation-routing.agentother6.4 KB
assets/patterns/lifecycle-events.agentother4.7 KB
assets/patterns/llm-controlled-actions.agentother5.1 KB
assets/patterns/multi-step-workflow.agentother10.1 KB
assets/patterns/open-gate-routing.agentother11.6 KB
assets/patterns/procedural-instructions.agentother4.8 KB
assets/patterns/prompt-template-action.agentother6.6 KB
assets/patterns/system-instruction-overrides.agentother10.6 KB
references/action-prompt-templates.mdmarkdown5.7 KB
references/actions-reference.mdmarkdown30.2 KB
references/agent-access-guide.mdmarkdown2.9 KB
references/agent-audit-and-repair.mdmarkdown7.9 KB
references/agent-audit-candidate-verification.mdmarkdown5.2 KB
references/agent-audit-diagnostic-catalog.mdmarkdown7.6 KB
references/agent-audit-diagnostics-actions-state.mdmarkdown6.9 KB
references/agent-audit-diagnostics-architecture-evaluation.mdmarkdown2.5 KB
references/agent-audit-diagnostics-instructions-routing.mdmarkdown11.8 KB
references/agent-audit-evaluation-loop.mdmarkdown6.0 KB
references/agent-audit-repair-report.mdmarkdown6.9 KB
references/agent-audit-scope-path-review.mdmarkdown8.5 KB
references/agent-design-and-spec-creation.mdmarkdown54.5 KB
references/agent-metadata-and-lifecycle.mdmarkdown30.2 KB
references/agent-script-core-language.mdmarkdown49.3 KB
references/agent-subagent-map-diagrams.mdmarkdown10.8 KB
references/agent-user-setup.mdmarkdown27.8 KB
references/agent-validation-and-debugging.mdmarkdown44.6 KB
references/agentscript-toolchain.mdmarkdown4.6 KB
references/architecture-patterns.mdmarkdown13.5 KB
references/common-control-flow-pitfalls.mdmarkdown9.4 KB
references/complex-data-types.mdmarkdown3.9 KB
references/control-flow-actions-sequencing.mdmarkdown6.9 KB
references/control-flow-lifecycle-side-effects.mdmarkdown3.3 KB
references/data-library-reference.mdmarkdown40.8 KB
references/deploy-reference.mdmarkdown6.7 KB
references/discover-reference.mdmarkdown4.3 KB
references/examples.mdmarkdown12.6 KB
references/feature-validity.mdmarkdown2.1 KB
references/instruction-resolution.mdmarkdown23.4 KB
references/known-issues.mdmarkdown27.6 KB
references/legacy-nga-regression-eval.mdmarkdown30.2 KB
references/mcp-management-reference.mdmarkdown37.6 KB
references/optimization-pattern-1-data-flow.mdmarkdown4.6 KB
references/optimization-pattern-2-deterministic-logic.mdmarkdown5.4 KB
references/optimization-pattern-3-reference-syntax.mdmarkdown4.1 KB
references/optimization-pattern-4-escalation.mdmarkdown2.2 KB
references/org-setup-for-adl.mdmarkdown23.7 KB
references/patterns-by-requirement.mdmarkdown5.4 KB
references/posture-and-determinism.mdmarkdown9.3 KB
references/production-gotchas.mdmarkdown12.6 KB
references/reference-map.mdmarkdown5.3 KB
references/safety-review-reference.mdmarkdown6.3 KB
references/salesforce-cli-for-agents.mdmarkdown16.7 KB
references/scaffold-reference.mdmarkdown6.7 KB
references/scoring-rubric.mdmarkdown3.3 KB
references/upgrade-legacy-agent-to-agentscript.mdmarkdown26.2 KB
references/version-history.mdmarkdown4.4 KB
references/voice-latency-heuristics.mdmarkdown9.7 KB
references/voice-modality-reference.mdmarkdown19.0 KB
references/voice-telephony-cli.mdmarkdown10.3 KB
references/zen-of-agentscript.mdmarkdown13.1 KB
scripts/__init__.pyscript0 B
scripts/agentscript-sdk-loader.mjsscript4.0 KB
scripts/discover.pyexecutablescript20.2 KB
scripts/generators/__init__.pyscript0 B
scripts/generators/apex_stub.pyscript13.4 KB
scripts/generators/apex_test_stub.pyscript3.8 KB
scripts/generators/flow_xml.pyscript7.6 KB
scripts/generators/permission_set_xml.pyscript1014 B
scripts/generators/remote_site_xml.pyscript1.4 KB
scripts/index-agent.mjsexecutablescript3.8 KB
scripts/org_describe.pyexecutablescript5.8 KB
scripts/scaffold.pyexecutablescript15.1 KB
scripts/setup-agentscript-sdk.mjsexecutablescript9.7 KB
scripts/upgrade-legacy-nga-analyze.pyexecutablescript20.0 KB
scripts/upgrade-legacy-nga-run-trials.shexecutablescript3.4 KB

references/agent-audit-scope-path-review.md

View on GitHub
# AgentScript Audit Scope and Path Review

Follow this first half of the audit workflow before selecting or applying a
repair level.

## Contents

- [Establish Scope and Evidence](#1-establish-scope-and-evidence)
- [Reconstruct the Use Cases](#2-reconstruct-the-use-cases)
- [Audit Every Reachable Path](#3-audit-every-reachable-path)

## Workflow

### 1. Establish Scope and Evidence

- Locate the complete `.agent` bundle, its metadata, action implementations,
  Agent Spec, test specifications, and relevant repository instructions.
- Determine whether the input is a complete agent, one extracted subagent, or
  a pasted fragment. Do not report missing bundle scaffolding as a defect in an
  intentionally extracted fragment.
- Inspect the worktree before editing. Preserve unrelated user changes.
- Identify available validation surfaces: Salesforce CLI and target org,
  project commands, preview, test suites, and session traces.
- Read the full agent and every directly referenced action contract needed to
  understand its behavior. Do not infer action outputs from names alone.
- Create the audit ledger or report shell now. Record artifact scope, baseline
  identity, evidence limits, initial use cases, and the highest-priority
  supported observations. Keep incomplete entries explicitly marked instead of
  withholding the artifact until the audit is complete.
- Run the strongest available read-only project check. If an authenticated
  target org and complete bundle are available, run:

  ```bash
  sf agent validate authoring-bundle --json --api-name <BundleName>
  ```

  Preserve the baseline diagnostics.

If only a fragment is available, perform a bounded semantic review and state
which structural, reachability, and runtime claims cannot be verified.

#### Scale the audit before reading a large agent

As a workflow heuristic, use the indexed audit below when a file is large
enough that a single-pass review would lose cross-node context. Rough defaults
are more than 2,000 lines or 10 execution nodes; adjust them to the density and
complexity of the artifact. They are not AgentScript runtime limits.

1. Build a deterministic index first: block boundaries, variables, actions,
   action outputs, transitions, lifecycle hooks, and available diagnostics.
   Follow [AgentScript Compiler Setup](agentscript-toolchain.md) to load an
   ambient SDK, install the public npm package, or build the public source
   fallback, then run
   `node <skill-directory>/scripts/index-agent.mjs <path-to-agent-file>` and
   retain its JSON outside the bundle. This helper uses the real
   parser/compiler rather than regex and reports its exact provider. If both
   installation paths fail, record **compiler not used** and continue with
   target-org validation or a bounded static review; do not stall the audit.
2. Seed one audit ledger keyed by execution node and use-case ID immediately
   after indexing. Do not rely on a single giant narrative summary.
3. Screen each node for user-visible harm and confidence. Add supported
   Critical and High findings to the ranked ledger as soon as they are found;
   do not wait for every node to be deeply traced.
4. Deep-trace the highest-ranked affected paths first. Open another reference
   or source file only after naming the decision its evidence could change.
   Stop a line of inquiry when two consecutive reads or queries add no material
   evidence to that decision.
5. Checkpoint the ledger after each reviewed node or coherent cause group. Mark
   remaining nodes as pending so an interrupted audit still leaves a useful,
   honest deliverable.
6. After the node screening pass, run one cross-node pass for shared variables,
   instruction overrides, transition arrivals, action ownership, and reset
   behavior, then revise the rankings.
7. Repair one coherent cause group per batch. Keep a coupled group small enough
   to attribute any regression, then run validation, affected regression cases,
   and representative unaffected canaries before the next batch.
8. Report deferred accepted findings after every batch. Do not hold the first
   useful result until the whole file has been rewritten.

Large size is not itself a defect. Do not split an agent merely to make the
analysis easier.

### 2. Reconstruct the Use Cases

Build a use-case matrix before fixing anything. Prefer, in order:

1. user-supplied behavior and acceptance criteria;
2. an approved Agent Spec;
3. existing tests and evaluation definitions;
4. reachable behavior inferred from the agent and action contracts.

Label inferred use cases. Do not quietly turn them into new requirements.

For each user-facing objective, record:

- initial utterance and required follow-up turns;
- expected response, question, action, transition, refusal, or escalation;
- actions that must be available and actions that must be unavailable;
- trusted prerequisites and expected state changes;
- external side effect, if any, and which mechanism owns it.

Include only the boundaries material to the artifact or user intent:

- positive path;
- missing or invalid input;
- failure and retry;
- cancellation or topic switch when supported;
- repeated request or repeated action;
- multi-turn continuation;
- transition arrival with the current customer message;
- explicit negative action-availability cases.

### 3. Audit Every Reachable Path

Trace each use case through:

```text
effective instructions
-> available actions
-> selected action or response
-> returned output
-> stored state
-> next reasoning iteration or transition
-> externally observable result
```

Apply every relevant category in the Diagnostic Catalog. Pay special attention
to:

- structural indentation versus indentation inside `|` text;
- repeated adjacent `|` markers that fragment one contiguous prompt block;
- runtime values named in `|` text without `{!@variables.X}` interpolation;
- exact machine-known comparisons whose consequences must be stable but are
  written as model prose instead of runtime predicates;
- subagent system instructions replacing global instructions;
- independent conditions that overlap or leave gaps;
- invalid `elif`, unsupported nested conditionals, or independent branches that
  should be one first-match `else if` chain;
- HyperClassifier used for a node that must do more than transition, or omitted
  from a compatible pure router despite an established routing-latency need;
- action availability broader than the prompt branch mentioning it;
- `|` prompt text treated as though it pauses deterministic `run`, `set`, or
  `if` resolution;
- a requested model action treated as executed merely because the model was
  told to call it;
- raw or stale outputs controlling consequential decisions;
- completion flags set before every derived field is usable;
- redundant state that encodes one phase several ways, duplicates conversation
  history, or lacks reset semantics;
- reasoning burden that exceeds the target model's demonstrated capability;
- lifecycle hooks that overwrite legitimate later state;
- unsupported syntax or lifecycle constructs;
- two mechanisms claiming the same side effect;
- tests that encode a new preference instead of existing intent.
- categorical or causal findings whose evidence supports only a recommendation,
  possibility, or version-specific observation.

Rank findings by observable harm, not visual ugliness:

- **Critical:** unsafe or unauthorized effect, data exposure, or systemic
  inability to perform the primary objective.
- **High:** wrong routing, wrong action, duplicate effect, dead primary path,
  or trusted decision based on untrusted data.
- **Medium:** reachable failure, retry, continuation, or maintenance defect
  with bounded impact.
- **Low:** concrete clarity or resilience defect with a plausible failure mode.

No location, consequence, use case, and verification plan means no finding.
A missing entry in an abbreviated reference list is not evidence of a defect.
Likewise, a style preference with no diagnostic, supported-use-case
consequence, or user-approved cleanup scope is not a Surface repair. Preserve
valid optional metadata and semantically equivalent control-flow shapes.
Do not add a supposedly required field to an existing bundle without a
diagnostic from the selected compiler or target validator and evidence for its
correct value. Never guess deployment semantics merely to complete a schema.

Keep the ranked ledger current while tracing. Finish the Critical and High
paths before spending time on Medium or Low hypotheses. A lower-priority issue
may be recorded as pending when further research would delay a supported,
higher-impact finding or repair.
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: 472kUpdated 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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated 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