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-and-repair.md

View on GitHub
# Audit and Repair Existing Agents

Repair an existing AgentScript agent without replacing its intended behavior
with generic preferences.

Org-backed validation requires an Agentforce-enabled org and Salesforce CLI.
A bounded static review can proceed without org access, but must not be
reported as compiler or runtime validation.

## Contents

- [Operating Contract](#operating-contract)
- [Surface Preservation Gate](#surface-preservation-gate)
- [Related Skill Boundaries](#related-skill-boundaries)
- [Workflow references](#workflow-references)

## Operating Contract

1. **Use cases define correctness.** A checklist can reveal risk; it cannot
   decide what the agent should do. Reconstruct the agent's intended use cases
   before recommending or making behavioral changes.
2. **Diagnose before editing.** Record the baseline, exact evidence, affected
   use cases, and smallest credible fix first.
3. **Make findings actionable.** Every finding must include a source location,
   runtime consequence, affected use case, proposed change, and verification
   method. Omit unsupported style opinions.
4. **Prefer the smallest repair.** Do not redesign the agent, add subagents,
   add persistent state, or add universal ambiguity, off-topic, or human-help
   behavior unless the use cases require it.
5. **Evaluate the control tradeoff.** Do not mechanically make every condition
   deterministic or leave every condition to the model. More control improves
   ordering and repeatability but costs flexibility, state, and maintenance.
   More model latitude improves interpretation and recovery but makes behavior
   probabilistic. Protect requirements whose failure cost warrants runtime
   control; preserve model judgment where flexibility is valuable. When the
   model needs a runtime value, inject it explicitly.
6. **Choose the intervention level.** After diagnosis, assess Surface,
   Structural, and Rewrite; recommend the smallest sufficient level, explain
   the alternatives and tradeoffs, and obtain user choice before Structural or
   Rewrite work. Never broaden the repair silently.
7. **Compile locally, then validate against the target org.** Run the bundled
   local compiler first. When an authenticated org is available, also use
   `sf agent validate authoring-bundle --json` for target-org language
   validation. Never claim language validity from a regex, a home-grown parser,
   or prompt inspection. Treat diagnostics as evidence, not an optimization
   score. Do not silence a diagnostic by violating documented AgentScript
   syntax, removing intentional initialization, or changing behavior. Treat
   reference lists and examples as guidance rather than exhaustive schemas.
   When references, examples, the selected compiler, and the target validator
   disagree, preserve an accepted existing construct, report the discrepancy,
   and validate against the intended deployment target instead of deleting the
   construct by inference.
8. **Compare like with like.** Run the same use cases and evaluators against
   the unchanged baseline and candidate. Label them explicitly. For Structural
   or Rewrite candidates, account for every material removal of a subagent,
   route, experience-specific branch, action, default, or user-visible
   response before claiming capabilities were preserved.
9. **Distinguish availability, invocation, execution, and effect.** A good
   response or tool name does not prove that an external side effect occurred.
10. **Calibrate every claim.** Distinguish language/compiler contracts,
    runtime-source behavior, observed trace behavior, empirical heuristics, and
    authoring recommendations. Do not turn a single trace, runtime version, or
    preferred design into a universal rule. Use causal or categorical wording
    only when the evidence supports it. Compilation alone supports “compiles”
    or “candidate for review.” Use “safe,” “behavior-preserving,” “ready to
    ship,” or equivalent language only when relevant behavior has also been
    evaluated; otherwise state what remains untested.
11. **Do not release.** This workflow authorizes local edits and proportionate
    validation, not deployment, publication, activation, production execution,
    or live consequential actions.
12. **Deliver useful work before exhaustive work.** Create a durable audit
    ledger or report shell after the initial scan, rank supported findings by
    observable harm, and update the artifact as evidence or repairs land. Do
    not make a complete runtime theory, complete reference review, or complete
    rewrite a prerequisite for the first useful deliverable.
13. **Bound investigation by decisions.** Follow a reference, source path, or
    trace only when it can change a named finding, repair, or verification
    decision. If a primary source and one relevant corroborating source do not
    resolve a non-safety-critical semantic question, record the uncertainty
    and proceed. If the uncertainty blocks a safe repair, deliver the ranked
    findings and blocker instead of continuing an open-ended investigation.
14. **Carry the contract into delegated work.** Give each delegated pass a
    bounded artifact or cause group, priority order, lookup-only references,
    and explicit output path. Require the first checkpoint after its initial
    scan and a useful partial report when blocked. Do not hand a delegate a
    broad mandatory reading list or an all-or-nothing final deliverable.

## Surface Preservation Gate

For a Surface-only request, use the original artifact as the byte-preserving
baseline:

1. List accepted findings before editing. Each must identify the original
   source text, evidence, concrete consequence, and exact intended edit.
2. Do not treat a draft as a generation task. Missing recommended fields,
   optional messages, preferred formatting, or equivalent control-flow forms
   are not repair findings by themselves.
3. Edit the existing bundle in place. Preserve its directory, API name,
   filenames, metadata, and equivalent control-flow form unless an accepted
   finding specifically requires changing one of them. Do not emit a renamed
   candidate bundle for an ordinary repair.
4. Apply only edits on the accepted list. Do not improve tone, complete a
   schema, reorder blocks, or normalize style opportunistically.
5. Diff the candidate against the baseline. Revert every hunk that cannot be
   mapped one-to-one to an accepted finding. If a hunk contains both required
   and unrelated cleanup, narrow it before delivery.
6. Validation is evidence, not permission to widen the repair. Do not change
   block-scalar style, normalize equivalent control flow, or migrate otherwise
   preserved metadata merely so an org validator can run; record the
   validation limit and keep the unrelated bytes unchanged.

This gate does not prevent evidence-backed Surface fixes. It prevents an
authoring preference from silently expanding a bounded repair.

Use [Diagnostic Catalog](agent-audit-diagnostic-catalog.md) as a lookup after
the initial scan; do not preload it. Consult the relevant section of
[Evaluation Loop](agent-audit-evaluation-loop.md) before recording a baseline,
applying a repair, or accepting a candidate; do not preload sections for later
steps.

## Related Skill Boundaries

- Use the parent skill's create or modify task domain for a new agent or one
  already-specified edit.
- Use `agentforce-observe` when production session or trace evidence is the
  primary input.
- Use `agentforce-test` when the task is only to author or run a predefined
  functional or security test suite.

## Workflow references

Read both workflow references in order for a full audit or repair:

1. [Audit Scope and Path Review](agent-audit-scope-path-review.md) — establish scope, scale large audits, reconstruct use cases, and inspect reachable paths.
2. [Audit Repair and Report](agent-audit-repair-report.md) — select the intervention level, preserve a baseline, repair, evaluate, and report.
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