@salesforce/afv-skills 1.31.0 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.31.0",
+  "version": "1.33.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/agentforce-bot-upgrade/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: agentforce-bot-upgrade
+description: "Use this skill to Upgrade Einstein Bots into Agentforce agents end-to-end in a single pass, orchestrating per-bot Agent Spec generation, planner reconciliation across bots, agentforce-generate authoring, and post-conversion .agent enhancements. TRIGGER when: user asks to migrate, upgrade, or convert one or more Einstein Bots to Agentforce; runs a multi-bot bot-to-agent upgrade; needs Einstein Bot metadata turned into Agent Spec handoffs and generated .agent agents; convert bots to agents; upgrade my service bots; move bots to Agentforce. DO NOT TRIGGER when: user already has an approved Agent Spec and only wants direct .agent authoring, deploy, test, or observe flows; the request is unrelated to Einstein Bot migration."
+argument-hint: "[--mode <online|offline>] [--org-alias <org-alias> --bots <bot1:v1,bot2:v2,...> | --offline-dir <offline-dir> [--bots <bot1,bot2,...>]] [--interactive <true|false>]"
+metadata:
+  version: "1.0"
+  minApiVersion: "63.0"
+  relatedSkills:
+    - "agentforce-generate"
+    - "agentforce-test"
+    - "agentforce-observe"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Einstein Bot Upgrade Orchestrator
+
+## Purpose
+
+Run a multi-bot upgrade-and-handoff cycle:
+
+1. Parse and validate bot/version pairs from `--bots`
+2. Follow [Generate Agent Spec Reference](references/generate-agent-spec.md) per bot-version pair (parallelizable)
+3. Aggregation step that requires all generated Agent Specs
+4. `/agentforce-generate` per Agent Spec (parallelizable)
+5. Post-conversion enhancement pass per generated Agent Script (parallelizable)
+
+## Inputs
+
+Inputs:
+- `--mode <online|offline>` is optional; default is `online` when omitted.
+- If `mode=online`, required:
+  - `--org-alias <org-alias>`
+  - `--bots <bot1:v1,bot2:v2,...>`
+- If `mode=offline`, required:
+  - `--offline-dir <offline-dir>`
+- `--interactive <true|false>` is optional; default is `true` when omitted.
+
+If required inputs are missing, handle per the Missing Input Handling and Interactive Mode rules below.
+
+## Interactive Mode
+
+`--interactive` controls whether the skill pauses for user input during execution:
+
+- `--interactive true` (default): resolve ambiguities, open questions, and approval gates by asking the user, as described in this skill and its references.
+- `--interactive false`: run autonomously. Do NOT prompt the user at any decision point. For every open question, ambiguity, or approval gate, apply the documented recommended default/solution and record the auto-applied decision in the run artifacts (Agent Spec, open questions, extraction summary). The only hard stops permitted without prompting are inputs that are missing or contradictory with no safe recommended default — a missing mandatory launch input (`--org-alias`/`--bots` for online, `--offline-dir` for offline), no bots discovered, or the same bot given multiple versions. In those cases, report the issue and halt without prompting.
+
+Propagate the effective `--interactive` value to the per-bot Generate Agent Spec workflow (Step 2), the planner workflow (Step 3), and the post-conversion enhancement pass (Step 5).
+
+## Missing Input Handling
+
+Resolve missing required launch inputs before Step 1:
+
+1. **Online mode — `--org-alias` not provided.** Resolve this before attempting to list bots (listing requires a target org).
+   - Interactive: list the available aliases of logged-in orgs and ask the user to select the target org. Use the SF CLI patterns in [SF CLI Bot Reference](references/sf-cli-bot-reference.md).
+   - Non-interactive: halt with an explicit error naming the missing `--org-alias` input (do not prompt or list).
+2. **Online mode — bot name and version (`--bots`) not available.**
+   - Interactive: using `--org-alias` as the target org, list every bot and its versions in the org, then ask the user to select the bot/version entries they want to convert to agents. Use the `BotDefinition` and `BotVersion` query patterns in [SF CLI Bot Reference](references/sf-cli-bot-reference.md) — omit the name/version filters to enumerate all bots and versions — present the results, and build the `--bots` workload from the user's selection.
+   - Non-interactive: halt with an explicit error naming the missing `--bots` input (do not prompt or list).
+3. **Offline mode — `--offline-dir` not available.**
+   - Interactive: ask the user to provide the `--offline-dir` path, then continue.
+   - Non-interactive: fail with an explicit error naming the missing `--offline-dir` input (do not prompt).
+
+## References
+
+Use these reference files during execution:
+
+1. [SF CLI Bot Reference](references/sf-cli-bot-reference.md)
+2. [Generate Agent Spec Reference](references/generate-agent-spec.md)
+3. [Planner Workflow Reference](references/planner-workflow-reference.md)
+4. [Post-Conversion Enhancements Reference](references/post-conversion-enhancements-reference.md)
+5. [Extraction Blueprint](references/extraction-blueprint.md)
+6. [Input Contract](references/input-contract.md)
+7. [Mapping Rules](references/mapping-rules.md)
+8. [Handoff Output Format](references/handoff-output-format.md)
+9. [Quality Checklist](references/quality-checklist.md)
+
+## Execution Contract
+
+### Step 1: Parse and Validate `--bots`
+
+Execute Step 1 in this order:
+
+1. Resolve mode:
+   - If `--mode` omitted, use `online`.
+2. Start fresh for this invocation:
+   - do not discover, inspect, or reuse outputs from previously existing runs
+   - treat this invocation as a clean execution context
+   - only use artifacts produced during the current invocation flow
+3. Build initial workload list:
+   - `mode=online`: read `--bots` and split by comma.
+   - `mode=offline`: scan `<offline-dir>` and collect immediate sub-directories as bot workload roots.
+4. Validate input shape:
+   - `mode=online`: each `--bots` token must match `<bot-name>:<version>`.
+   - `mode=offline`: ensure at least one bot sub-directory exists; otherwise STOP (in interactive mode ask the user to clarify; in non-interactive mode halt with an explicit error per the Interactive Mode rule).
+5. Normalize workload entries:
+   - `mode=online`: build `{bot_name, bot_version}` entries.
+   - `mode=offline`: build `{offline_bot_dir}` entries (Annotate inferred bot name and version when derivable from the sub-directory structure; if not derivable, leave the entry unnamed and continue).
+6. Enforce one-version-per-bot rule (online mode):
+   - If the same `bot_name` appears with multiple versions, STOP (in interactive mode ask the user to clarify; in non-interactive mode halt with an explicit error per the Interactive Mode rule).
+7. Apply offline bot filter:
+   - If `mode=offline` and `--bots` is provided, use `--bots` only as a filter over discovered sub-directories; do not treat it as required offline input.
+8. Persist Step 1 output:
+   - Save and carry forward a validated workload list for Step 2 parallel execution.
+
+### Step 2: Run Einstein Bot Upgrade (Per Bot-Version)
+
+Execute the agent spec generation workflow from [Generate Agent Spec Reference](references/generate-agent-spec.md) per bot-version combination:
+- `--mode <online|offline>` (default `online` if omitted)
+- mode-specific required inputs:
+  - online -> `--org-alias`, `--bot`, `--bot-version`
+  - offline -> `--offline-dir`
+- `--interactive <true|false>` (pass through the effective orchestrator value; default `true`)
+
+Parallelization rule:
+- In `mode=online`, execute invocations in parallel because each bot-version pair is independent.
+- In `mode=offline`, execute the [Generate Agent Spec Reference](references/generate-agent-spec.md) workflow in parallel over every bot sub-directory discovered in Step 1.
+  - Pass `--mode offline` and `--offline-dir <bot-subdirectory-path>` per invocation.
+Ensure each invocation (online/offline) uses isolated working directories to avoid cross-run file collisions.
+
+Hard rules:
+- Do not skip this step.
+
+### Step 3: Aggregation + Planner Step (Conditional)
+
+After all upgrade invocations complete:
+
+1. Always build a consolidated list of `{bot_name, bot_version, run_project_dir, agent_spec_path}`.
+2. Always build list of failed/incomplete upgrade runs (if any).
+3. Always build an initial ready-for-authoring list containing only valid Agent Spec entries.
+   - Each entry must include: `{bot_name, bot_version, run_project_dir, agent_spec_path, handoff_json_path, open_questions_path}`.
+4. If total bot workload count is greater than 1:
+   - Execute planner workflow from [Planner Workflow Reference](references/planner-workflow-reference.md) using:
+     - all ready-for-authoring `agent_spec_path` values as `spec_paths`
+     - orchestrator working directory as `working_dir`
+     - the associated per-spec artifacts from each ready-for-authoring entry: `handoff_json_path` (handoff JSON) and `open_questions_path` (open questions)
+   - Require output file at `<orchestrator working directory>/bot-upgrade-planner-output.json`.
+   - Read `bot-upgrade-planner-output.json` and apply:
+     - if `specs_changed=true`: replace ready-for-authoring entries using planner fields (`updated_spec_path`, `run_project_dir`, `handoff_json_path`, `open_questions_path`)
+     - if `specs_changed=false`: keep original ready-for-authoring list unchanged
+5. If total bot workload count is 1:
+   - Skip planner workflow entirely.
+   - Keep original ready-for-authoring list unchanged.
+
+Planner output expectations:
+1. boolean `specs_changed`
+2. `updated_specs` array with entries:
+   - `original_spec_path`
+   - `updated_spec_path`
+   - `run_project_dir`
+   - `handoff_json_path`
+   - `open_questions_path`
+3. `updated_specs` must be empty when `specs_changed=false`
+
+### Step 4: Invoke Agentforce-Generate (Per Agent Spec)
+
+For each entry in final ready-for-authoring list (post Step 3 planner reconciliation):
+
+0. Add this recommendation to the generated invocation context before calling `/agentforce-generate`:
+   - Do **not activate** Agent Script versions in this orchestrated run.
+   - Draft iteration is required: generating `.agent`, validating, deploying, and preview testing are allowed.
+   - Activate should be deferred unless the user explicitly asks for release.
+1. Resolve effective `run_project_dir` from the final ready-for-authoring entry.
+2. Read `<run_project_dir>/agentforce-generate-invocation-prompt.md` fully.
+3. If Step 3 produced planner-updated spec paths/artifacts, apply path substitutions in the invocation context so spec/handoff/open-questions references point to updated files.
+   - If planner also changed `run_project_dir`, use that updated `run_project_dir` for resolving prompt/output-contract paths.
+4. Keep all non-path instructions unchanged from the original generated prompt.
+5. Invoke `/agentforce-generate` with this resolved invocation context.
+6. Read `<run_project_dir>/agentforce-generate-output-contract.md` and capture outputs exactly as specified.
+
+Parallelization rule:
+- Invoke `/agentforce-generate` in parallel across Agent Specs because each run is independent.
+
+Output-contract capture rules:
+
+1. Treat the output contract as authoritative for required fields/artifacts.
+2. If any contract field is missing, mark status as partial and list missing fields explicitly.
+3. Return captured outputs with deterministic keys matching the contract names.
+4. Preserve output file paths and status of each required artifact.
+5. If expected prompt/contract files are missing for an entry, mark that entry `partial`, record missing paths, and continue processing other entries.
+
+### Step 5: Post-Conversion Agent Script Enhancements (Per Generated Agent Script)
+
+After Step 4 completes, for each generated `.agent` artifact:
+
+1. Resolve the generated `.agent` file path from captured `/agentforce-generate` outputs.
+2. Execute post-conversion enhancement workflow from [Post-Conversion Enhancements Reference](references/post-conversion-enhancements-reference.md) with:
+   - `agentscript_file=<generated-agent-file-path>`
+   - `mode=<online|offline>` (the effective orchestrator run mode resolved in Step 1)
+   - online mode only: `org_alias=<org-alias>` (required so the enhanced Agent Script can be redeployed)
+3. Require in-place enhancement:
+   - optimized/enhanced output must be written to the same `.agent` file location.
+4. Capture per-file enhancement status and any partial failures.
+
+Parallelization rule:
+- Execute post-conversion enhancement workflow in parallel across generated `.agent` files because each file enhancement is independent.
+
+### Step 6: Consolidate Run Report and Conclude
+
+After Step 5 completes for every bot in the workload:
+
+1. Write a single consolidated, human-readable run report as a non-empty Markdown file in the orchestrator working directory. Per bot, the report must state: the effective run mode, whether the planner ran (`executed` or `skipped`), the generated Agent Spec path and generated `.agent` path, the action inventory (including any `NEEDS_STUB` items), and — when `--interactive=false` — the auto-applied decisions.
+2. Treat the run report as the FINAL artifact: write it only after all other artifacts (Agent Spec(s), handoff JSON, open questions, any planner output, and generated `.agent` file(s)) are already written.
+
+## Deliverable
+
+Return:
+1. parsed bot/version list
+2. per-bot upgrade execution status
+3. aggregation output (full Agent Spec list + final ready-for-authoring subset)
+4. planner workflow status (`executed` or `skipped`) and `bot-upgrade-planner-output.json` path when executed
+5. per-spec `/agentforce-generate` execution status
+6. generated handoff artifact paths per bot/spec (including planner-updated artifacts when applicable)
+7. captured `/agentforce-generate` outputs per output contract
+8. per-agent post-conversion enhancement status (including enhanced `.agent` file paths)
+9. path to the consolidated run report written in Step 6

package/skills/agentforce-bot-upgrade/references/extraction-blueprint.md

@@ -0,0 +1,242 @@
+# Extraction Blueprint
+
+## Goal
+
+Extract only migration-relevant behavior from Einstein Bot and discard transport noise.
+
+## Required Extractions
+
+### 1) Dialog Graph
+
+**Input files:**
+
+Paths below are shown relative to the bots root directory. For org-backed retrieval this root is the SFDX default metadata directory `force-app/main/default/` (so the full path is `force-app/main/default/bots/<BotName>/…`, as retrieved in [SF CLI Bot Reference](sf-cli-bot-reference.md) section 3). For offline input this root is the provided `--offline-dir` (e.g. `bots/`).
+
+- `bots/<BotName>/<BotName>.bot-meta.xml` (bot-level metadata)
+- `bots/<BotName>/<version>.botVersion-meta.xml` (dialog + step graph source of truth)
+
+**Build the graph with this process:**
+
+1. Parse every `<botDialogs>` block in `<version>.botVersion-meta.xml` as one node.
+2. For each node, capture:
+   - `developerName` (node id)
+   - `label`
+   - `mlIntent` (if present)
+   - `dialogGroup` / grouping metadata if present
+3. Treat each `<botSteps>` entry inside a dialog as a step in execution order.
+4. While scanning each step, also detect action invocations and variable mappings from bot steps:
+   - invocation/action step types (for example `Invocation`)
+   - action identifier/name and invocation type (`apex`, `flow`, `standardInvocableAction`, etc.)
+   - variables read by the action (bot variables passed as invocation inputs)
+   - variables updated by the action (bot variables set from invocation outputs)
+   - escalation actions from system messages:
+     - if a dialog contains `conversationSystemMessage` of type `Transfer`, add an action entry with `action_type: "escalate"`
+     - determine escalation target type (`queue`, `flow`, `bot`, or `skill`) by reading `systemMessageMappings` under that `conversationSystemMessage` and resolving referenced variables against declarations in `<conversationVariables>`
+     - store both the resolved `target_type` and mapped target identifier/value on the action record
+   - persist this as `invoked_actions` on the dialog node and as action-level records in `action_inventory`
+5. While scanning each step, detect transition-producing step types:
+   - `Navigation` with `<botNavigationLinks>`
+   - `Group` containing nested `Navigation`
+   - `Wait` type steps, which define intent-driven routing points (intent redirect behavior)
+6. For every discovered transition, add one directed edge:
+   - `source_dialog` -> `targetBotDialog`
+   - `type` (`redirect`, `call`, `intent_redirect`)
+7. Capture conditions from enclosing step/group when present:
+   - `leftOperandName`
+   - `operatorType`
+   - `rightOperandValue`
+   - store as a normalized condition expression on the edge
+8. Mark graph role hints:
+   - probable entry dialogs (for example `Welcome`, `Main_Menu`, or system entry mapping)
+   - terminal dialogs (for example paths ending in `SystemMessage` + `EndChat`, with no outbound navigation)
+
+**Required output for dialog graph extraction:**
+
+```json
+{
+  "nodes": [
+    {
+      "dialog": "Main_Menu",
+      "label": "Main Menu",
+      "intent": "Main_Menu",
+      "invoked_actions": [
+        {
+          "action_name": "Airline_Get_User_Details",
+          "action_type": "flow",
+          "variables_read": ["user_email"],
+          "variables_written": ["airline_user", "is_success"]
+        }
+      ]
+    }
+  ],
+  "edges": [
+    {
+      "source": "Main_Menu",
+      "target": "Bookings_Menu",
+      "type": "redirect",
+      "condition": null
+    }
+  ]
+}
+```
+
+**Quality checks:**
+
+- Every `targetBotDialog` in edges must resolve to an existing dialog node.
+- Keep `Call` and `Redirect` distinct (do not merge semantics).
+- Preserve multiple outgoing edges from the same step when configured.
+
+### 2) Intent Layer
+
+- Intent name/developer name
+- Intent description
+- Linked dialogs
+- Intent examples/utterances (if available)
+
+**Intent summarization workflow:**
+
+1. For each dialog node in the dialog graph, read its `mlIntent` value (if present).
+2. Treat that `mlIntent` as the lookup key for intent metadata in `MlDomain` with the same name.
+3. From the matched intent metadata, extract:
+   - `developerName`
+   - `label` / `description` (if present)
+   - `mlIntentUtterances` (training utterances)
+4. Generate a concise intent summary (2-3 sentences) per unique intent:
+   - sentence 1: user goal the intent represents
+   - sentence 2: typical phrasing style inferred from `mlIntentUtterances`
+   - sentence 3 (optional): routing nuance or disambiguation hint if overlapping with other intents
+5. If an `mlIntent` is referenced by a dialog but no matching `MlDomain` intent is found:
+   - flag the intent as unresolved
+   - add it to `open_questions`
+   - still generate a provisional summary from dialog label/description with `confidence: low`
+
+### 3) Variable and Entity Layer
+
+**Input files:**
+
+- `bots/<BotName>/<BotName>.bot-meta.xml` (context variables, slot/entity metadata)
+- `bots/<BotName>/<version>.botVersion-meta.xml` (conversation variable usage through steps)
+
+**Variable extraction and typing rules:**
+
+1. Extract context variables from `bot-meta.xml` (`<contextVariables>` entries).
+2. Mark every context variable as:
+   - `variable_type: linked`
+   - `data_type`: map from bot metadata `dataType`
+   - `source`: derive from context mappings (`SObjectType` + `fieldName`) when present
+3. Extract conversation variables directly from `botVersion-meta.xml` `<conversationVariables>` entries (authoritative source for declared conversation variables).
+4. Mark every conversation variable as:
+   - `variable_type: mutable`
+   - `data_type`: read directly from the variable's declared data type in `<conversationVariables>`
+
+**Required output shape (variables):**
+
+```json
+{
+  "variables": [
+    {
+      "name": "ContactId",
+      "data_type": "Id",
+      "variable_type": "linked",
+      "source": "MessagingEndUser.ContactId"
+    },
+    {
+      "name": "Complaint_Id",
+      "data_type": "Text",
+      "variable_type": "mutable"
+    }
+  ]
+}
+```
+
+### 4) Action/Invocation Layer
+
+- Action name and invocation type (`apex`, `flow`, etc.)
+- Inputs, outputs, and variable mappings
+- Also extract knowledge-backed action signals from `botVersion-meta.xml`:
+  1. If `knowledgeActionEnabled` is `true`:
+     - add an action entry with `action_type: "knowledge"`
+     - include `knowledgeActionEnabled: true`
+  2. If `knowledgeFallbackEnabled` is `true`:
+     - add an action entry with `action_type: "knowledge"`
+     - include `knowledgeFallbackEnabled: true`
+- When both fields are `true`, capture both flags (either on one combined knowledge action record or two explicit knowledge action records), but ensure both booleans are present in extracted output.
+
+**Offline mode signature generation (required):**
+
+When input mode is offline (`.bot-meta.xml` + `.botVersion-meta.xml` provided, no org fetch):
+
+1. Generate action signatures from bot metadata mappings only (do not block on missing Apex/Flow source code).
+2. For each invocation mapping:
+   - extract action parameter names from invocation input/output mapping keys
+   - resolve mapped bot variable names from mapping values
+   - infer parameter types from mapped variable declarations in `<conversationVariables>` / `<contextVariables>` when available
+3. If type cannot be inferred, use a conservative placeholder type (`Text` or `Object`) and flag in notes/open questions.
+4. Keep unresolved/partial signatures as non-blocking and continue extraction.
+
+**Signature construction rules:**
+
+1. Do not copy bot variable names as action parameter names unless metadata explicitly uses the same name.
+2. Preserve both layers in output:
+   - contract layer: `input_name` / `output_name`, `type`
+   - mapping layer: `mapped_variable`, `variable_type` (`mutable` or `linked`)
+3. For each signature entry, capture direction explicitly:
+   - `direction: input` for values read by the action
+   - `direction: output` for values written by the action
+4. If one action is invoked multiple times with different mappings, keep one action signature and record per-call mapping context separately (for example `call_context`).
+
+### 5) Dialog Clusters and Categorization
+
+After extracting actions and dialog/action mappings, categorize bot functionality into dialog clusters.
+
+1. Classify actions into groups using these priority criteria (highest priority first):
+   - actions working on the same underlying entity SHOULD be grouped together
+   - actions writing/updating the same variable SHOULD be grouped together
+   - actions reading the same input variable CAN be grouped together
+   - actions invoked by dialogs in the same dialog group CAN be grouped together
+   - actions with similar intent CAN be grouped together
+2. Keep group size between:
+   - minimum: 1 action
+   - maximum: 4 actions
+   If a group exceeds 4 actions, split it while preserving higher-priority criteria.
+3. An action may belong to multiple groups when criteria requires an overlap.
+4. Assign dialogs to groups based on associated actions:
+   - for each grouped action, trace back dialogs that invoke it
+   - include those dialogs in the corresponding dialog cluster
+   - maintain an `action_dialog_mapping` for each group (`action -> [dialogs]`)
+5. Generate a short functional description (2-3 sentences) per group using grouped actions and associated dialogs.
+
+## Extraction Output Shape
+
+Build an intermediate extraction summary used by mapping:
+
+```json
+{
+  "run_identity": {},
+  "dialog_graph": {
+    "nodes": [],
+    "edges": []
+  },
+  "intent_catalog": {},
+  "variables": {},
+  "action_inventory": {},
+  "dialog_clusters": {},
+  "unmapped_items": {}
+}
+```
+
+## Persist Extraction Output
+
+Write the extraction summary to a JSON file before starting mapping.
+
+- Output filename: `extraction-summary.json`
+- Output location: same working/output directory used for the current bot/version handoff artifacts
+- The file content must preserve the extraction output shape defined above
+- If extraction is rerun, overwrite this file with the latest extraction snapshot
+
+`action_inventory` should include any extracted knowledge action entries with explicit `knowledgeActionEnabled` and/or `knowledgeFallbackEnabled` boolean flags when present in bot version metadata.
+
+## Extraction Principles
+
+- Favor explicit configured behavior over assumptions.
+- Preserve branch conditions where available.

package/skills/agentforce-bot-upgrade/references/generate-agent-spec.md

@@ -0,0 +1,128 @@
+# Generate Agent Spec
+
+## What This Skill Is For
+
+This skill implements **only Phase 1 of migration**:
+
+- **In scope**: Einstein Bot -> normalized migration model -> Agent Spec handoff package
+- **Out of scope**: `.agent` generation, validation, publish, activate, or deployment
+
+The generated handoff is explicitly designed so `/agentforce-generate` can consume it as the starting spec input for Agent Script authoring.
+
+## How to Use This Skill
+
+Treat this file as the execution router. Always read the referenced files before executing each step.
+
+Follow this fixed sequence:
+
+1. Intake and normalize source bot artifacts
+2. Build migration mapping model (dialogs/intents/entities/actions/transitions)
+3. Generate Agent Spec handoff artifacts for `/agentforce-generate`
+4. Resolve open questions with the user one-by-one (or auto-apply recommended defaults when `--interactive=false`) and persist decisions
+5. Generate handoff invocation prompt for `/agentforce-generate` when ambiguity is cleared
+
+## Rules That Always Apply
+
+1. **Do not generate `.agent` in this skill.** Stop at Agent Spec + handoff artifacts.
+2. **No implementation invention.** If action target details are unknown, use `NEEDS_STUB`.
+3. **Preserve behavioral intent, not XML shape.** Convert deterministic bot flow into subagent-oriented behavioral design.
+4. **Track uncertainty explicitly.** Every ambiguous mapping must be captured in `open_questions`.
+5. **Mandatory resolution loop.** After artifact generation, process open questions and persist every resolved decision. In interactive mode, resolve them one-by-one with the user; when `--interactive=false`, auto-apply the recommended default for each open question without prompting and record the decision.
+6. **Prompt handoff after clarity.** Once all open questions are resolved without ambiguity, generate a complete invocation prompt package for `/agentforce-generate` (do not invoke the skill from this skill).
+7. **Use deterministic guardrails for risky flows.** Identity checks, escalation, sensitive operations, and regulated advice must be explicit in the spec.
+8. **Input gate is a hard block.** Do not read any workspace files, bot metadata, Apex classes, SFDX project contents, or existing spec files until input mode is explicitly selected and all required inputs for that mode are confirmed. Speculative reading of artifacts found in the workspace is prohibited.
+
+## Task Domains
+
+### Build Agent Spec from Einstein Bot
+
+Use this when user provides Einstein Bot artifacts and asks to migrate/upgrade into Agentforce.
+
+#### Required Steps
+
+0. **Collect mode and required inputs (HARD GATE)** — Parse inputs using this contract:
+   - `--mode <online|offline>` (optional; default to `online` when omitted)
+   - If `mode=online`, required inputs:
+     - `--org-alias <org-alias>`
+     - `--bot <bot-name>`
+     - `--bot-version <bot-version>`
+   - If `mode=offline`, required input:
+     - `--offline-dir <offline-dir>` (directory containing/associated with bot metadata inputs)
+   - `--interactive <true|false>` (optional; default `true`). When `false`, run autonomously: do not prompt at any decision point, apply the recommended default for every open question/ambiguity, and record each auto-applied decision.
+   If required mode-specific inputs are missing, stop and ask in interactive mode; in non-interactive mode halt with an explicit error (do not prompt). Do not read files/metadata/workspace contents until mode and required inputs are confirmed.  
+   Note: if `--mode` is omitted, treat mode as `online` immediately (do not ask user to choose mode in that case).
+
+1. **Ingest source artifacts** — Read [Input Contract](input-contract.md) and normalize user-provided bot inputs into one canonical migration model.
+   - For `mode=online`, run required SF CLI bot/version/dependency retrieval using [SF CLI Bot Reference](sf-cli-bot-reference.md). Use ONLY the query patterns documented there — do NOT invent or modify field names.
+   - For `mode=offline`, skip org retrieval and process **all relevant local metadata** from `--offline-dir`:
+     - bot and botVersion XML metadata (required)
+     - Flow metadata under `flows/` (when present)
+     - Apex classes under `classes/` (when present)
+     - any other local files referenced by bot artifacts that are needed for extraction/mapping fidelity
+   - In offline mode, do not limit ingestion to only two XML files if additional referenced artifacts are available locally.
+2. **Extract migration structure** — Read [Extraction Blueprint](extraction-blueprint.md) and derive:
+   - bot capabilities
+   - dialog graph
+   - intent map
+   - variable/entity usage
+   - invocation/action inventory
+   - fallback/escalation behavior
+3. **Map Einstein Bot -> Agent Spec components** — Read [Mapping Rules](mapping-rules.md) and produce topic/subagent, action, routing, and state mappings.
+4. **Generate handoff artifacts** — Read [Handoff Output Format](handoff-output-format.md) and write:
+   - `<run_project_dir>/<AgentName>-AgentSpec.md`
+   - `<run_project_dir>/<AgentName>-einstein-bot-handoff.json`
+   - `<run_project_dir>/<AgentName>-open-questions.md`
+   Use the same run-specific SFDX project directory created in the SF CLI setup step; do not write handoff artifacts to repository root.
+   The Agent Spec markdown MUST use the same section names/order as
+   `skills/agentforce-generate/assets/agent-spec-template.md`, then append the
+   `## Migration Notes (Einstein Bot -> Agentforce)` appendix defined in [Handoff Output Format](handoff-output-format.md).
+5. **Validate handoff quality** — Read [Quality Checklist](quality-checklist.md) and verify all required sections and mapping completeness before presenting output.
+6. **Resolve open questions loop (required)** — After generating artifacts, resolve all entries in `<run_project_dir>/<AgentName>-open-questions.md`. In interactive mode, guide the user through them one-by-one; when `--interactive=false`, auto-apply the recommended default for each entry without prompting. For each resolved item, immediately update:
+   - `<run_project_dir>/<AgentName>-AgentSpec.md`
+   - `<run_project_dir>/extraction-summary.json`
+   and remove/mark-resolved the corresponding open question.
+7. **Generate `/agentforce-generate` invocation package (no direct invoke here)** — When all open questions are resolved without ambiguity, generate and persist:
+   - `<run_project_dir>/agentforce-generate-invocation-prompt.md` (the exact prompt to pass to `/agentforce-generate`)
+   - `<run_project_dir>/agentforce-generate-output-contract.md` (expected outputs that orchestrator must capture)
+   The prompt must include:
+   - `current_working_directory` (run folder path) for all reads/writes
+   - `<run_project_dir>/<AgentName>-AgentSpec.md` as source-of-truth spec
+   - `<run_project_dir>/extraction-summary.json` as supporting context
+   - `<run_project_dir>/<AgentName>-einstein-bot-handoff.json` and `<run_project_dir>/<AgentName>-open-questions.md`
+   - `input_mode` (`online` or `offline`) explicit context
+   For `input_mode=offline`, include these strict instructions in the prompt:
+   - syntax/structural validation is still mandatory
+   - skip only org-dependent CLI operations
+   - use local artifacts only
+   - keep unresolved implementations as structurally complete `NEEDS_STUB` action definitions
+   - do not deploy/publish/activate
+   Do not invoke `/agentforce-generate` from this skill.
+
+#### Reference Files
+
+1. [Input Contract](input-contract.md) — accepted source types and normalization schema
+2. [Extraction Blueprint](extraction-blueprint.md) — what to extract from Einstein Bot metadata and why
+3. [Mapping Rules](mapping-rules.md) — canonical mapping from bot constructs to Agent Spec constructs
+4. [Handoff Output Format](handoff-output-format.md) — required output files and exact structure
+5. [Quality Checklist](quality-checklist.md) — validation criteria before handoff to `/agentforce-generate`
+6. [SF CLI Bot Reference](sf-cli-bot-reference.md) — required `sf` command sequence to validate bot/version and retrieve dependencies
+
+## Deliverables
+
+At completion, always return:
+
+1. Agent Spec handoff file path
+2. Handoff JSON path
+3. Open questions path
+4. `/agentforce-generate` invocation package status:
+   - `generated` with prompt/output-contract paths when all open questions are resolved
+   - `blocked` when unresolved ambiguity remains (include unresolved question IDs)
+5. Generated `/agentforce-generate` invocation prompt path (when status is `generated`)
+6. Generated `/agentforce-generate` output contract path (when status is `generated`)
+7. Short migration-risk summary (top unresolved items)
+
+## Important Constraints
+
+- Do not invoke deployment/publish/activate flows in this skill.
+- Do not claim parity with Einstein Bot unless all dialogs/intents/actions are mapped or explicitly deferred.
+- Do not collapse critical decision branches into vague LLM-only behavior; represent gates and transitions explicitly in the Agent Spec.