@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/agentforce-bot-upgrade/references/handoff-output-format.md

@@ -0,0 +1,208 @@
+# Handoff Output Format
+
+## Required Files
+
+1. `<AgentName>-AgentSpec.md`
+2. `<AgentName>-einstein-bot-handoff.json`
+3. `<AgentName>-open-questions.md`
+
+The extraction step also persists `extraction-summary.json` in the same directory (see [Extraction Blueprint](extraction-blueprint.md)); it is carried forward as supporting context in the handoff.
+
+Write all required files in the run-specific SFDX project directory for the selected input mode:
+- Mode A: org-backed run project directory created during SF CLI setup
+- Mode B: offline run project directory containing/associated with provided XML inputs
+Do not write handoff artifacts in the repository root.
+
+## 1) Agent Spec Markdown
+
+Create `<run_project_dir>/<AgentName>-AgentSpec.md` by copying:
+`skills/agentforce-generate/assets/agent-spec-template.md`
+
+The handoff Agent Spec MUST:
+
+1. retain the same section names and ordering as the template
+2. fill every section with migration-specific content derived from extraction outputs
+
+Required section order:
+
+1. `## Purpose & Scope`
+2. `## Behavioral Intent`
+3. `## Subagent Posture`
+4. `## Subagent Map`
+5. `## Variables`
+6. `## Actions`
+7. `## Action Invocation Strategy`
+8. `## Deterministic Controls (When Needed)`
+9. `## Architecture Pattern`
+10. `## Agent Configuration`
+
+### Section-by-section generation guidance (from `extraction-summary.json`)
+
+#### `## Purpose & Scope`
+
+1. Derive a meaningful purpose statement from bot description/identity and extracted intent summaries.
+2. Describe the agent's business scope using the intents the bot actually handles.
+3. Restrict scope to capabilities backed by configured actions:
+   - do not claim unsupported capabilities
+   - call out out-of-scope requests when no action support exists
+
+#### `## Behavioral Intent`
+
+1. Start traversal from `Welcome` (or extracted entry dialog when `Welcome` is absent).
+2. Build each workflow using:
+   - `dialog_functionality_summary`
+   - ordered `step_functionality`
+3. Handle navigations by following target dialogs recursively, while preserving navigation semantics:
+   - **`Call` navigation**: transfer control to the target dialog, then return control back to the source dialog after target execution completes. Continue source-dialog remaining steps after return.
+   - **`Redirect` navigation**: transfer control permanently to the target dialog and halt source-dialog execution immediately (no return to source flow).
+4. While reconstructing flows, track `Call` vs `Redirect` semantics internally so downstream agent design preserves return/non-return behavior.
+5. For `Call` flows, capture both:
+   - the delegated target workflow behavior, and
+   - the resumed source workflow behavior after return.
+6. For `Redirect` flows, do not append post-redirect source steps to the same path unless there is an explicit later re-entry edge.
+7. Reconstruct meaningful user conversation flows across traversed dialogs.
+8. Identify hard checkpoints by capturing strict ordering constraints, mandatory preconditions, and enforced branches/escalations.
+9. Final behavioral intent must include:
+   - ordered events for one or more workflows
+   - action invocation scope and sequencing
+   - variable usage scope (reads/writes and gating variables)
+   - escalation/routing behavior
+   - normalized transition behavior (return-after-delegation vs one-way transfer) expressed in agent-native terms only
+   - other critical bot-specific constraints that affect conversation behavior
+
+10. Do NOT emit raw bot navigation constructs (`Call`, `Redirect`) in the final Agent Spec text. Convert them into agent-native behavioral descriptions only.
+
+#### `## Subagent Posture`
+
+1. Derive baseline subagents from dialog clusters (`1 cluster -> 1 subagent`).
+2. Ensure each subagent has coherent responsibility boundaries based on associated dialog behavior and actions.
+3. Add additional subagents when dialogs are not assigned to any cluster but represent distinct bot functionality.
+4. Ensure all dialog functionality is covered by at least one subagent.
+5. Record any uncertain assignments in open questions instead of forcing low-confidence grouping.
+
+### Bot-specific artifact translation rules (required)
+
+When generating the Agent Spec, do not retain raw bot-only entities. Translate them into agent-native behavior.
+
+1. Do not carry forward bot-only references directly, including:
+   - intent names derived from dialog naming
+   - intent utterance lists as bot-training artifacts
+   - dialog identifiers/names
+   - menu redirection constructs
+2. Replace each with equivalent capability-level descriptions:
+   - user goal summaries
+   - behavioral routing intent
+   - reasoning instructions for when/how to route or invoke actions
+3. Menu redirections must be translated by:
+   - capturing the user intent behind each menu option
+   - converting each option into an equivalent reasoning-based LLM instruction
+   - preserving functional outcomes without reproducing rigid bot menu mechanics
+4. Evaluate every bot return message/response shown to users:
+   - if a message contains no actionable information and is only small talk, ignore it
+   - otherwise, preserve equivalent user-facing messaging in the relevant subagent behavior
+   - do not miss messages containing information about next steps, required actions, documentation, policy, or handoff guidance
+5. For each subagent, evaluate whether menu translation is necessary at all:
+   - prefer direct intent/reasoning behavior when menus are unnecessary
+   - retain a lightweight guided-choice pattern only when it materially improves clarity or control
+6. If menu translation approach is ambiguous, ask the user and record the decision in open questions before finalizing. When `--interactive=false`, do not ask — apply the recommended translation, record it in open questions as an auto-applied decision, and continue.
+
+Then add this migration-specific appendix section at the end:
+
+11. `## Migration Notes (Einstein Bot -> Agentforce)`
+    - Source bot identity and version
+    - Mapping confidence summary
+    - Unmapped constructs
+    - Open decisions requiring user approval
+
+### Action Invocation Optimization Rules
+
+Use this step to optimize conversation efficiency by reducing unnecessary action invocations while preserving behavior and data contracts.
+
+#### Allowed optimization operations
+
+1. **Add action** — only when required to preserve an existing conversational outcome after removing/replacing bot-only behavior.
+2. **Update action** — only for invocation optimization (for example, replacing multi-hop equivalent invocations with one semantically equivalent action).
+3. **Delete action** — only when action is bot-only or redundant in the agent architecture.
+
+#### Hard constraints
+
+1. Do not merge or modify unrelated actions just to reduce invocation count.
+2. Do not change action inputs/outputs in a way that causes data loss.
+3. Preserve all variable assignments needed by downstream steps/subagents.
+4. Preserve required action side effects that are part of business behavior.
+
+#### Bot-only action handling
+
+If an action is applicable only to Einstein Bot runtime (for example, internal bot-state bookkeeping actions):
+
+1. Mark the action as `candidate_for_removal`.
+2. Show the user why it is bot-only and why it is not needed in Agentforce.
+3. Do not remove it automatically.
+4. Remove only after explicit user confirmation. When `--interactive=false`, do not remove it — keep the action in place as the safe recommended default and record it as a deferred `candidate_for_removal` decision in open questions.
+
+#### User review gate (required)
+
+When `--interactive=false`, skip the interactive review: apply only non-destructive recommended optimizations (adds/updates), never auto-delete actions, record every applied and deferred change in open questions, then treat those recommended changes as final without prompting.
+
+Before finalizing optimized actions, present a complete change summary to the user:
+
+1. Added actions
+2. Updated actions
+3. Candidate removals
+4. For each affected action, include:
+   - action description/purpose
+   - full input contract
+   - full output contract
+   - variable assignments (reads/writes)
+   - rationale for optimization
+
+Apply changes only after user approval.
+
+#### Persistence requirement
+
+After user confirms, update the Agent Spec file to reflect all finalized action changes (adds/updates/deletes), including:
+
+- action descriptions
+- input/output contracts
+- variable read/write assignments
+- action invocation strategy updates required by the optimization
+
+Do not treat non-confirmed changes as final.
+
+## 2) Open Questions Markdown
+
+Include:
+
+- Blocking decisions (must resolve before `/agentforce-generate` handoff)
+- Non-blocking clarifications (resolve when they materially affect generated spec/actions)
+- Recommended defaults for each question
+
+Write this file as:
+
+- `<run_project_dir>/<AgentName>-open-questions.md`
+
+## 3) Einstein Bot Handoff JSON
+
+Create `<run_project_dir>/<AgentName>-einstein-bot-handoff.json` as a machine-readable companion to the Agent Spec markdown, derived from `extraction-summary.json` and the mapping produced per [Mapping Rules](mapping-rules.md).
+
+The handoff JSON MUST:
+
+1. Capture the structured mapping used to build the spec:
+   - subagent/topic mapping
+   - action inventory with input/output contracts and `EXISTS`/`NEEDS_STUB`/`NEEDS_CREATION`/`CANDIDATE_FOR_REMOVAL` status
+   - variable mappings (`mutable`/`linked`)
+   - routing/transition mapping
+   - unmapped items
+2. Stay aligned with the finalized Agent Spec markdown — after the open-questions loop completes, regenerate it so it reflects the resolved spec before handoff (no contradictory mappings).
+
+## Open Question Resolution Loop (Required)
+
+After generating initial artifacts, resolve open questions one-by-one with the user. When `--interactive=false`, do not prompt — auto-apply the recommended default recorded for each question and mark it resolved.
+
+For each resolved question:
+
+1. Update `<run_project_dir>/<AgentName>-AgentSpec.md` with the resolved decision.
+2. Update `<run_project_dir>/extraction-summary.json` with the same resolved finding and any downstream mapping updates.
+3. Mark the question as resolved (or remove it) in `<run_project_dir>/<AgentName>-open-questions.md`.
+
+Do not leave ambiguous or contradictory outcomes in any artifact.

package/skills/agentforce-bot-upgrade/references/input-contract.md

@@ -0,0 +1,101 @@
+# Input Contract
+
+## Mode Selection
+
+Input mode is selected from `--mode <online|offline>`:
+
+1. **Online (Mode A: org-backed retrieval)** — Use org alias + bot identity, then fetch metadata/dependencies via SF CLI.
+2. **Offline (Mode B: local metadata input)** — Use provided local metadata/artifacts directly without org fetch.
+
+If `--mode` is omitted, default to **online**.
+Only ask the user to clarify mode when provided inputs are insufficient or contradictory for the inferred/default mode. When `--interactive=false`, do not ask — proceed with the inferred/default mode and record the assumption; halt only if the inputs cannot support any mode.
+
+## Supported Input Modes
+
+### Mode A: Org-backed retrieval
+
+Required inputs:
+
+1. `--org-alias <org-alias>` — Salesforce org alias used as source context (for discovery, validation, and traceability).
+2. `--bot <bot-name>` — Einstein Bot developer name/identifier to migrate.
+3. `--bot-version <bot-version>` — specific version to migrate (for example: `v3`).
+
+### Mode B: Offline metadata input (new)
+
+Required inputs:
+
+1. `--offline-dir <offline-dir>` — directory containing/associated with local bot metadata inputs.
+
+Within `--offline-dir`, `.bot-meta.xml` and `.botVersion-meta.xml` inputs are treated as authoritative bot metadata sources for extraction/mapping.
+
+## Offline Directory Processing Scope (Required)
+
+When `--mode offline` is selected, process **all relevant local artifacts** in `--offline-dir` (recursively), not just bot XML:
+
+1. Bot metadata:
+   - `*.bot-meta.xml`
+   - `*.botVersion-meta.xml`
+2. Flow artifacts:
+   - files under `flows/` (for example `*.flow-meta.xml`)
+3. Apex artifacts:
+   - files under `classes/` (for example `*.cls`, `*.cls-meta.xml`)
+4. Misc referenced artifacts:
+   - any other files referenced by bot/flow/action mappings that improve extraction/mapping fidelity
+
+Processing rules:
+
+1. If `flows/` exists, parse flow signatures and mappings to improve action inventory contracts.
+2. If `classes/` exists, parse invocable Apex signatures (`@InvocableMethod`, `@InvocableVariable`) to improve action I/O contracts.
+3. If both bot mapping and local implementation artifacts exist, prefer concrete local implementation signatures over inferred placeholders.
+4. If referenced artifacts are missing locally, continue with inferred signatures and mark unresolved details in `open_questions`.
+5. Never require org retrieval in offline mode.
+
+If required inputs for the selected mode are missing, stop and ask for them before processing artifacts.
+
+## Identity Resolution Rules
+
+- For Mode A, use `org-alias + bot + bot-version` as the run identity key.
+- For Mode B, use `bot + bot-version` derived from provided XML metadata (or confirmed from user when not derivable).
+- Do not merge artifacts from different versions in the same run.
+- If source files contain a mismatched bot identity, pause and ask the user which identity is authoritative. When `--interactive=false`, do not pause — treat the identity declared in the authoritative bot metadata as the recommended default and record the assumption in `open_questions`.
+
+## Missing/Partial Input Handling
+
+- If action signatures are missing: keep action in inventory with `target: NEEDS_STUB`.
+- If intent training data is missing: infer intent purpose from dialog labels/descriptions and mark confidence.
+- If transitions are unclear: preserve as unresolved branch in `open_questions`.
+
+## Post-Input Finalization Workflow (Required)
+
+### Mode A: Org-backed retrieval
+
+After `--org-alias + --bot + --bot-version` are finalized, execute the SF CLI sequence in:
+
+- [SF CLI Bot Reference](sf-cli-bot-reference.md)
+
+This is the canonical command list for:
+
+1. Enforcing SF CLI and org access prerequisites
+2. Validating bot and bot version
+3. Retrieving bot metadata
+4. Retrieving required Apex/Flow/ML domain dependencies
+
+Any unresolved dependency must be recorded in `open_questions` and mapped as `NEEDS_STUB` where applicable.
+
+### Mode B: Offline metadata input
+
+When both XML files are provided (`.bot-meta.xml` + `.botVersion-meta.xml`):
+
+1. Create a run folder in repo root named `<bot-name>-<bot-version>-agent`.
+2. Copy the provided bot metadata files into that run folder:
+   - `<BotName>.bot-meta.xml`
+   - `<version>.botVersion-meta.xml`
+3. Use that run folder as the working directory for this offline run.
+4. Skip all SF CLI org validation/retrieval commands.
+5. Do not fetch bot/dependency metadata from org.
+6. Continue directly with extraction and mapping using all available local artifacts in `--offline-dir` as source inputs.
+7. If `flows/` and/or `classes/` are present, include them in extraction before finalizing action contracts.
+8. If referenced dependencies (Apex/Flow/MLDomain/etc.) are not available locally, record them as unresolved in `open_questions` and map as `NEEDS_STUB` where applicable.
+9. If action signatures (Apex/Flow/etc.) cannot be fully resolved in offline mode, continue execution with best-effort signature expansion and mark unresolved fields.
+
+All generated outputs for that run (for example `extraction-summary.json`, Agent Spec handoff, and open questions) must be written inside the same run-specific SFDX project directory for the selected mode.

package/skills/agentforce-bot-upgrade/references/mapping-rules.md

@@ -0,0 +1,113 @@
+# Mapping Rules
+
+## Objective
+
+Convert extracted Einstein Bot behavior into a high-quality Agent Spec that `/agentforce-generate` can execute.
+
+## Canonical Mappings
+
+- **Dialog clusters** -> **Subagents/Topics**
+- **Intent catalog** -> **Router instructions + transition actions**
+- **Entity/slot collection** -> **Variables + eligibility/guard conditions**
+- **Action inventory** -> **Action inventory in spec** (`NEEDS_STUB` when implementation unknown)
+- **Fallback dialogs** -> **Boundary handling and recovery behavior**
+- **Transfer/system handoff** -> **Built-in `@utils.escalate`** (escalation policy; never a new/standalone action)
+
+## Escalation Mapping Rule
+
+Escalation/transfer behavior (Einstein Bot `SystemMessage` `Transfer`, or any "hand off to a live agent/human" handoff) MUST be mapped implicitly to the built-in `@utils.escalate` utility. Do NOT:
+
+- create a new action for it in the action inventory (no `Transfer_To_Agent`-style action, no `NEEDS_STUB`/`NEEDS_CREATION` entry for the transfer),
+- model it as a flow/apex/standard-invocable action, or
+- represent it as generic "hand off to a human" prose without the explicit `@utils.escalate` control.
+
+Instead:
+
+- Express the escalation as an explicit `@utils.escalate` invocation in the relevant subagent's instructions (typically a terminal step of an escalation subagent).
+- Exclude the transfer from the action inventory entirely (it is not an authored action).
+
+## Dialog Functionality Extraction Rules
+
+Capture the functional behavior of each bot dialog before action optimization.
+
+### Processing steps
+
+1. Process each bot dialog independently.
+2. Parse the dialog's bot steps strictly in configured order.
+3. For each bot step, generate one or more meaningful functional sentences that describe what the bot does at that step.
+4. Build an ordered list per dialog (`step_functionality`) that preserves original step sequence.
+
+### What each step description must capture
+
+For each step, include applicable details:
+
+- step intent/purpose (message, collect, invoke, transition, system behavior)
+- conditions/guards (for example variable comparisons and branching criteria)
+- action invocations (action name and type, when invoked)
+- variable updates (set/unset/collect, including affected variable names)
+- transition behavior (target dialog and transition type when present)
+
+### Exhaustive bot-step handling
+
+When generating `step_functionality`, handle all supported Einstein Bot step families using the rules below.
+
+1. **Message**
+   - Describe user-facing message intent and any branch context.
+2. **VariableOperation**
+   - **Set**: capture source -> target variable assignment.
+   - **Unset**: capture variable clear/reset behavior.
+   - **Collect**: capture which variable is collected, requiredness, and option source (static/dynamic).
+   - **SetConversationLanguage**: capture locale/language state update.
+   - **CollectAttachment**: capture file-collection requirement and resulting variable update.
+3. **Invocation**
+   - Capture invocation target, invocation type (`apex`, `flow`, `standardInvocableAction`, `externalService`, `quickAction`, `api`), input mappings, output mappings, and resulting variable writes.
+4. **Navigation**
+   - Capture transition type (`Redirect` / `Call`), target dialog, and trigger condition.
+5. **Wait**
+   - Capture as intent-routing pause point where control waits for user input and may route to intent-enabled dialogs.
+6. **Group**
+   - Process nested steps recursively in order, preserving parent conditions and emitting child step sentences in sequence.
+7. **SystemMessage**
+   - **Transfer**: capture escalation behavior and resolved target type/value, and map it implicitly to the built-in `@utils.escalate` (see Escalation Mapping Rule) — do not emit it as a new action.
+   - **EndChat**: capture terminal behavior and conversation close.
+8. **RecordLookup**
+   - Capture queried object/entity, filter criteria, and output variable/list assignment.
+9. **RichMessage**
+   - Capture rich interaction type (for example forms/payments/selectors/links) and expected follow-up behavior.
+10. **GoalStep**
+    - Mark as bot-specific/non-agentic telemetry unless it drives business behavior; include only if behaviorally relevant.
+
+### Step rendering rules
+
+1. Preserve original step order exactly.
+2. Emit one or more concise functional sentences per step.
+3. Include conditional prefix when step is gated (for example `If <condition> ...`).
+4. Preserve variable names and action names verbatim in step descriptions.
+5. Do not skip nested steps inside `Group`.
+
+### Output requirement
+
+For every dialog, produce:
+
+1. `dialog_functionality_summary` (short high-level summary)
+2. `step_functionality` (ordered list of functional sentences derived step-by-step)
+
+This output is the baseline for downstream subagent grouping and mapping decisions.
+
+## Risk and Safety Rules
+
+- Explicitly capture:
+  - identity verification points
+  - sensitive action boundaries
+  - escalation to human support
+  - refusal boundaries for unsupported asks
+
+## Persistence Requirement
+
+At the end of mapping, update `extraction-summary.json` with bot dialog functionality details for every dialog, including `dialog_functionality_summary` and ordered `step_functionality`.
+
+When updating `extraction-summary.json` during mapping:
+
+1. Preserve the canonical schema defined in [Extraction Blueprint](extraction-blueprint.md) (do not add/remove/rename top-level keys).
+2. Update existing sections in place (`dialog_graph`, `intent_catalog`, `variables`, `action_inventory`, `dialog_clusters`, `unmapped_items`) instead of reshaping them.
+3. Keep enum/status normalization stable (`redirect/call/intent_redirect`; `EXISTS/NEEDS_STUB/NEEDS_CREATION/CANDIDATE_FOR_REMOVAL`).

package/skills/agentforce-bot-upgrade/references/planner-workflow-reference.md

@@ -0,0 +1,78 @@
+# Planner Workflow Reference
+
+Use this reference during orchestrator Step 3 when processing multiple bots in a single invocation.
+
+## When To Apply
+
+- Apply only when there are more than 1 ready-for-authoring Agent Specs.
+- If there is 1 or fewer specs, skip planner workflow and keep specs unchanged.
+
+## Inputs
+
+Required inputs to this workflow:
+
+1. `spec_paths`: all ready-for-authoring Agent Spec paths
+2. `working_dir`: orchestrator working directory where planner output must be written
+3. associated artifacts for each spec when present:
+   - handoff JSON
+   - open questions
+
+## Required Workflow
+
+1. Read all specs and associated artifacts.
+2. Build a final candidate set of specs that will each map to one actual downstream agent.
+3. Identify existing subagent grouping/context in each spec.
+4. Attempt regrouping based on:
+   - intent
+   - underlying object/entity
+   - broad category
+5. Allowed structural operations across specs:
+   - merge
+   - split
+   - move
+   - delete
+6. Apply operations only when they improve:
+   - modularity
+   - context-awareness
+   - interactive user experience
+7. Never perform changes for superficial consistency only.
+8. Preserve full functional coverage:
+   - no input functionality may be lost
+   - if any functionality loss risk is detected, abandon changes and mark unchanged
+
+## Required Output File
+
+Write:
+- `<working_dir>/bot-upgrade-planner-output.json`
+
+Schema:
+
+```json
+{
+  "specs_changed": true,
+  "updated_specs": [
+    {
+      "original_spec_path": "/path/original/spec-a.md",
+      "updated_spec_path": "/path/updated/spec-a.md",
+      "run_project_dir": "/path/updated/run-project-dir",
+      "handoff_json_path": "/path/updated/spec-a-einstein-bot-handoff.json",
+      "open_questions_path": "/path/updated/spec-a-open-questions.md"
+    }
+  ]
+}
+```
+
+Rules:
+
+1. `specs_changed` is boolean.
+2. If `specs_changed=false`, then `updated_specs=[]`.
+3. If `specs_changed=true`, `updated_specs` must include entries for all changed specs.
+4. Every changed entry must include:
+   - `original_spec_path`
+   - `updated_spec_path`
+   - `run_project_dir`
+   - `handoff_json_path`
+   - `open_questions_path`
+5. If any functionality-loss risk exists, force:
+   - `specs_changed=false`
+   - `updated_specs=[]`

package/skills/agentforce-bot-upgrade/references/post-conversion-enhancements-reference.md

@@ -0,0 +1,67 @@
+# Post-Conversion Enhancements Reference
+
+Use this reference during orchestrator Step 5 after `/agentforce-generate` completes.
+
+## Scope
+
+Apply per generated Agent Script artifact (`.agent`) independently.
+
+## Inputs
+
+Required:
+
+1. `agentscript_file`: path to one generated `.agent` file
+2. `mode` (`online|offline`): the effective orchestrator run mode
+
+Conditionally required:
+
+3. `org_alias`: target org alias used to redeploy in Step 9. Required when `mode=online`; omit when `mode=offline`.
+
+## Required Workflow
+
+1. Read the full `.agent` file.
+2. Enforce `start_agent` router behavior:
+   - ensure the subagent marked `start_agent` contains explicit instructions that 
+        - it is only a router and should route immediately to the correct downstream agent
+        - it never responds directly to the user
+   - if this instruction is missing, add it
+3. Improve transition quality with meaningful `available when` conditions:
+   - add or refine conditions between subagents wherever possible
+   - conditions should be meaningful and correct for transition intent
+   - conditions should reduce routing noise and improve next-step navigation in the final agent
+4. Validate action data flow integrity:
+   - ensure action inputs/outputs are correctly mapped through conversation variables or LLM inputs
+   - where needed, persist required LLM-derived values via `setVariables`
+   - ensure downstream actions can consume required values deterministically
+5. Enforce numeric action I/O typing:
+   - when an action input/output is numeric and flows between actions (e.g. rewards points
+     feeding a merchandise action), use the publish-safe form: an object field with
+     `complex_data_type_name: lightning__numberType`, not a bare `number`, so numeric typing
+     survives publish across all orgs.
+6. Validate escalation mapping:
+   - ensure any escalation/transfer behavior (Einstein Bot `SystemMessage` `Transfer`, or any "hand off to a live agent/human") is implemented via the built-in `@utils.escalate` utility.
+   - confirm escalation is NOT modeled as a standalone/new action: there must be no `Transfer_To_Agent`-style action and no action-inventory entry (including `NEEDS_STUB`/`NEEDS_CREATION`) representing the transfer.
+   - if the escalation is present in bot and missing in spec, or was authored as an action instead of `@utils.escalate`, fix it: remove the erroneous action and invoke `@utils.escalate` in the appropriate escalation subagent (keeping any resolved transfer target as a variable/context, not an action signature).
+7. Preserve intended functionality and behavioral coverage.
+8. Write the optimized/enhanced content back to the same file path (in-place update).
+9. Validate the resulting file:
+   - remains readable and structurally coherent
+   - is a valid Agent Script
+10. If enhancements modified the Agent Script:
+   - when `mode=online`, deploy/publish the updated Agent Script to the org again using the provided `org_alias`
+   - do not activate as part of this step
+   - when `mode=offline`, skip deploy and keep the updated local file only
+
+## Output
+
+- Enhanced Agent Script at the same input file location.
+
+## Capture Requirements
+
+For each processed file, capture:
+
+1. `agentscript_file`
+2. status (`success` or `partial`)
+3. short enhancement summary
+4. `agentscript_modified` (`true|false`)
+5. redeploy status (online mode only): `deployed`, `skipped`, or `failed`

package/skills/agentforce-bot-upgrade/references/quality-checklist.md

@@ -0,0 +1,33 @@
+# Quality Checklist
+
+Run this checklist before handing off to `/agentforce-generate`.
+
+## Completeness
+
+- Input mode is explicitly recorded for the run (Mode A org-backed or Mode B offline).
+- Agent Spec uses the exact section names/order from `assets/agent-spec-template.md` in `agentforce-generate`.
+- Every major bot capability is represented in the Agent Spec.
+- Every critical dialog/intent/action is either mapped or listed in `unmapped_items`.
+- Fallback and escalation behavior is explicit.
+
+## Fidelity
+
+- Action purpose and I/O are preserved from source metadata where available.
+- For Mode B (offline), action signatures are inferred from bot metadata mappings and unresolved signature details are tracked in `open_questions` (non-blocking).
+- Dialog-to-subagent and intent-to-subagent mappings are consistent.
+- High-risk flows contain clear deterministic guidance.
+
+## Handoff Readiness
+
+- Agent Spec markdown is coherent and structured for implementation.
+- Handoff JSON is machine-readable and aligned with markdown.
+- Open questions are specific, non-duplicative, and decision-ready.
+- Open questions are resolved — one-by-one with the user in interactive mode, or auto-applied from recommended defaults when `--interactive=false` — and each resolution is reflected in both Agent Spec and `extraction-summary.json`.
+- Migration appendix is present and includes confidence, gaps, and approval gates.
+
+## Failure Conditions (must fix before handoff)
+
+- Missing action inventory for flows that clearly invoke actions
+- Claimed parity while unresolved items are not documented
+- Ambiguous routing with no fallback
+- Unresolved or ambiguous open questions remain before automatic handoff to `/agentforce-generate`