@salesforce/afv-skills 1.6.9 → 1.7.0

package/package.json

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

package/skills/developing-agentforce/README.md

@@ -0,0 +1,112 @@
+# Agentforce Development Skill
+
+A Claude Code skill for building, modifying, debugging, and deploying Agentforce agents using Agent Script — Salesforce's scripting language for next-generation AI agents on the Atlas Reasoning Engine.
+
+## What This Skill Does
+
+Agent Script was introduced in 2025 with zero training data in any AI model. This skill bridges that gap by providing structured reference material, design patterns, CLI workflows, and debugging guidance so that AI coding assistants can work with Agent Script accurately.
+
+The skill covers the full Agent Script lifecycle:
+
+| Domain | What It Handles |
+|--------|----------------|
+| Create an Agent | Agent Spec design, environment validation, bundle generation, code authoring |
+| Modify an Agent | Topic/action changes, instruction refinement, flow control updates |
+| Create or Modify Backing Logic | Invocable Apex stubs, Flow wrappers, Prompt Templates |
+| Deploy and Publish | Source deploy, agent activation, publishing to channels |
+| Diagnose Compilation Errors | Compiler error interpretation, syntax fixes, metadata resolution |
+| Diagnose Behavioral Issues | Trace-based debugging, topic routing, action I/O analysis |
+| Diagnose Production Issues | Runtime failures, reserved keyword conflicts, deployment gotchas |
+| Test an Agent | Utterance-based validation, preview with live actions, trace analysis |
+| Generate Diagrams | Topic map visualizations, agent architecture diagrams |
+
+## Skill Structure
+
+```
+developing-agentforce/
+├── SKILL.md                    # Router — maps user intent to task domains and reference files
+├── references/                 # Domain knowledge (14 files)
+│   ├── agent-script-core-language.md
+│   ├── agent-design-and-spec-creation.md
+│   ├── agent-validation-and-debugging.md
+│   ├── salesforce-cli-for-agents.md
+│   ├── agent-metadata-and-lifecycle.md
+│   ├── agent-access-guide.md
+│   ├── agent-user-setup.md
+│   ├── actions-reference.md
+│   ├── action-prompt-templates.md
+│   ├── agent-topic-map-diagrams.md
+│   ├── minimal-examples.md
+│   ├── known-issues.md
+│   ├── production-gotchas.md
+│   └── version-history.md
+├── assets/                     # Templates, examples, and starter agents
+│   ├── agent-spec-template.md
+│   ├── invocable-apex-template.cls
+│   ├── bundle-meta.xml
+│   ├── patterns/               # Reusable Agent Script patterns
+│   ├── agents/                 # Annotated example agents
+│   ├── apex/                   # Apex backing logic examples
+│   ├── components/             # LWC components for agent channels
+│   ├── metadata/               # Metadata templates
+│   └── *.agent                 # Starter agent templates
+└── staging/                    # Unmerged reference material awaiting review
+```
+
+## How It Works
+
+SKILL.md acts as a router. It detects user intent from task descriptions, maps to a task domain, and instructs the AI assistant to read the relevant reference files before starting work. Reference files are loaded on demand — the assistant only reads what the current task requires.
+
+Three rules apply across all domains:
+
+1. **Always `--json`** on every `sf` CLI command
+2. **Diagnose before you fix** — preview with live actions and read traces before modifying code
+3. **Spec approval is a hard gate** — never proceed past Agent Spec creation without user approval
+
+## Prerequisites
+
+- Salesforce org with Agentforce license
+- API version 66.0+ (Spring '26)
+- Einstein Agent User (for service agents)
+- Salesforce CLI v2.x (`sf` command)
+- Claude Code (or compatible AI coding agent)
+
+## Installation
+
+Copy the `developing-agentforce` folder into your project's `.claude/skills/` directory:
+
+```
+your-project/
+└── .claude/
+    └── skills/
+        └── developing-agentforce/
+            ├── SKILL.md
+            ├── references/
+            └── assets/
+```
+
+Restart Claude Code after installation.
+
+## Version
+
+Current version: **0.4.9** (2026-03-20). See [references/version-history.md](references/version-history.md) for the full changelog.
+
+## Credits
+
+This skill integrates knowledge from the following sources:
+
+**Jag Valaiyapathy** ([sf-skills](https://github.com/Jaganpro/sf-skills), MIT License)
+— Known issues catalog, production gotchas, agent access and permissions guide, and deployment patterns. Integrated starting in v0.4.2.
+
+**Hua Xu** (Salesforce APAC FDE team)
+— Open-gate routing pattern from Kogan agent deployment.
+
+**Salesforce DevRel** ([agent-script-recipes](https://github.com/trailheadapps/agent-script-recipes))
+— Canonical Agent Script examples used as grounding material.
+
+**Dylan Zeigler, AI Platform** (llm-utils)
+— Agent Script playground used as reference source.
+
+## License
+
+Apache-2.0

package/skills/{agentforce-development → developing-agentforce}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: agentforce-development
-description: "Use this skill when working with Salesforce Agent Script — the scripting language for authoring Agentforce agents using the Atlas Reasoning Engine. Triggers include: creating, modifying, or comprehending Agent Script agents; working with AiAuthoringBundle files or .agent files; designing topic graphs or flow control; producing or updating an Agent Spec; validating Agent Script or diagnosing compilation errors; previewing agents or debugging behavioral issues; deploying, publishing, activating, or deactivating agents; deleting or renaming agents; authoring AiEvaluationDefinition test specs or running agent tests. This skill teaches Agent Script from scratch — AI models have zero prior training data on this language. Do NOT use for Apex development, Flow building, Prompt Template authoring, Experience Cloud configuration, or general Salesforce CLI tasks unrelated to Agent Script."
+name: developing-agentforce
+description: "Build, modify, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, modifies, or asks about .agent files or aiAuthoringBundle metadata; changes agent behavior, responses, or conversation logic; designs agent topics, actions, tools, sub-agents, or flow control; writes or reviews an Agent Spec; previews, debugs, deploys, publishes, or tests agents; uses Agent Script CLI commands (sf agent generate/preview/publish/test). DO NOT TRIGGER when: Apex development, Flow building, Prompt Template authoring, Experience Cloud configuration, or general Salesforce CLI tasks unrelated to Agent Script."
 license: Apache-2.0
 compatibility: "Requires Agentforce license, API v66.0+, Einstein Agent User"
 metadata:
-  version: "0.4.8"
-  last_updated: "2026-03-17"
+  version: "0.5.1"
+  last_updated: "2026-04-08"
 ---
 
 # Agent Script Skill
@@ -32,9 +32,11 @@ Identify user intent from task descriptions. ALWAYS read indicated reference fil
 
 ## Rules That Always Apply
 
-1. **Always `--json`.** ALWAYS include `--json` on EVERY `sf` CLI command.
+1. **Always `--json`.** ALWAYS include `--json` on EVERY `sf` CLI command. Do NOT pipe CLI output through `jq` or `2>/dev/null`. Read the full JSON response directly — LLMs parse JSON natively.
 
-2. **Diagnose before you fix.** When validating/debugging agent behavior,
+2. **Verify target org.** Before any org interaction, run `sf config get target-org --json` to confirm a target org is set. If none configured, ask the user to set one with `sf config set target-org <alias>`.
+
+3. **Diagnose before you fix.** When validating/debugging agent behavior,
    ALWAYS `--use-live-actions` to preview authoring bundles. Send utterances
    then read resulting session traces to ground your understanding of the
    agent's behavior. Trace files reveal topic selection, action I/O, and
@@ -42,7 +44,7 @@ Identify user intent from task descriptions. ALWAYS read indicated reference fil
    this grounding. See [Validation & Debugging](references/agent-validation-and-debugging.md)
    for trace file locations and diagnostic patterns.
 
-3. **Spec approval is a hard gate.** Never proceed past Agent Spec
+4. **Spec approval is a hard gate.** Never proceed past Agent Spec
    creation without explicit user approval.
 
 ## Task Domains
@@ -57,10 +59,10 @@ User wants to build new agent from scratch. ALWAYS use Agent Script. Work with U
 
 Read [CLI for Agents](references/salesforce-cli-for-agents.md) for exact command syntax.
 
-1. **Design** — Read [Design & Agent Spec](references/agent-design-and-spec-creation.md) to draft an Agent Spec. Always ask if you should scan for existing backing logic. Unless instructed otherwise, scan by reading `sfdx-project.json` to identify package directories, then search each for `@InvocableMethod` in `classes/`, `AutoLaunchedFlow` in `flows/`, and template metadata in `promptTemplates/`. Mark matches `EXISTS`; unmatched actions `NEEDS STUB`. **Always save Agent Spec as file.**
+1. **Design** — Read [Design & Agent Spec](references/agent-design-and-spec-creation.md) to draft an Agent Spec. Always ask if you should scan for existing backing logic. Unless instructed otherwise, scan by reading `sfdx-project.json` to identify package directories, then search each for `@InvocableMethod` in `classes/`, `AutoLaunchedFlow` in `flows/`, and template metadata in `promptTemplates/`. Mark matches `EXISTS`; unmatched actions `NEEDS STUB`. Also scan `objects/` for `.object-meta.xml` to discover custom objects — related objects often contain data the agent should expose even when not mentioned in the prompt. **Always save Agent Spec as file.**
 2. **STOP for user approval of Agent Spec.** Present to user. Ask for approval or feedback. **Do not proceed** without approval. Once approved, proceed without stopping unless a step fails.
 3. **Validate environment prerequisites** — Read [Design & Agent Spec](references/agent-design-and-spec-creation.md), Section 3 (Environment Prerequisites). Based on agent type from design, validate org environment:
-   - **Employee agent**: Confirm config block does NOT include `default_agent_user`. Remove if present.
+   - **Employee agent**: Confirm config block does NOT include `default_agent_user`, `connection messaging:`, or MessagingSession linked variables. Remove if present. See [Examples](references/examples.md) for a complete employee agent example.
    - **Service agent**: Query org for Einstein Agent User. If one exists, confirm username with user. If none, guide user through creation. See [CLI for Agents](references/salesforce-cli-for-agents.md), Section 12 for creation steps and [Agent User Setup](references/agent-user-setup.md) for required permissions.
    **Do not proceed to code generation until environment is validated.**
 4. **Generate authoring bundle** —
@@ -81,7 +83,12 @@ Read [CLI for Agents](references/salesforce-cli-for-agents.md) for exact command
    Send test utterances with:
    `sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"`
    Confirm topic routing, gating, and action invocations match Agent Spec. If behavior diverges, switch to **Diagnose Behavioral Issues** workflow. Return AFTER correcting issues.
-9. **Publish** — **DO NOT proceed until step 8 passes.** Publish validates metadata structure, not agent behavior. ALWAYS validate behavior before publishing. Every publish creates permanent version number.
+   **CHECKPOINT — Do NOT proceed to Publish unless ALL are true:**
+   - `validate authoring-bundle` passes with zero errors
+   - Live preview (`--use-live-actions`) tested with representative utterances per topic
+   - Traces confirm correct topic routing and action invocation
+   - User explicitly approves deployment
+9. **Publish** — Publish validates metadata structure, not agent behavior. Every publish creates permanent version number.
    `sf agent publish authoring-bundle --json --api-name <Developer_Name>`
    If publish fails, follow troubleshooting checklist in [Metadata & Lifecycle](references/agent-metadata-and-lifecycle.md), Section 5 before retrying.
 10. **Activate** — Makes new version available to users.
@@ -113,6 +120,12 @@ Read [CLI for Agents](references/salesforce-cli-for-agents.md) for exact command
    access permissions, visibility troubleshooting
 9. [Known Issues](references/known-issues.md) — only load when errors
    persist after code fixes
+10. [Architecture Patterns](references/architecture-patterns.md) — hub-and-spoke, verification gate, post-action loop
+11. [Complex Data Types](references/complex-data-types.md) — type mapping decision tree
+12. [Safety Review](references/safety-review-reference.md) — 7-category safety review
+13. [Discover Reference](references/discover-reference.md) — target discovery CLI
+14. [Scaffold Reference](references/scaffold-reference.md) — stub generation CLI
+15. [Deploy Reference](references/deploy-reference.md) — deployment lifecycle, error recovery
 
 ### Comprehend an Existing Agent
 
@@ -168,7 +181,12 @@ Read [CLI for Agents](references/salesforce-cli-for-agents.md) for exact command
    Send test utterances with:
    `sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"`
    Test changed paths first, then adjacent paths to catch regressions in existing behavior.
-8. **Publish** — **DO NOT proceed until step 7 passes.** Publish validates metadata structure, not agent behavior. ALWAYS validate behavior before publishing. Every publish creates permanent version number.
+   **CHECKPOINT — Do NOT proceed to Publish unless ALL are true:**
+   - `validate authoring-bundle` passes with zero errors
+   - Live preview (`--use-live-actions`) tested with representative utterances per topic
+   - Traces confirm correct topic routing and action invocation
+   - User explicitly approves deployment
+8. **Publish** — Publish validates metadata structure, not agent behavior. Every publish creates permanent version number.
    `sf agent publish authoring-bundle --json --api-name <Developer_Name>`
    If publish fails, follow troubleshooting checklist in [Metadata & Lifecycle](references/agent-metadata-and-lifecycle.md), Section 5 before retrying.
 9. **Activate** — Makes new version available to users.
@@ -270,8 +288,13 @@ Read [CLI for Agents](references/salesforce-cli-for-agents.md) for exact command
    `sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>`
    then send test utterances with:
    `sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>"`
-   Test key conversation paths to validate agent behavior when backed by live actions. **Do not proceed to Publish until preview passes.**
-4. **Publish** — **Publish validates metadata structure, not agent behavior.** ALWAYS validate behavior with live preview BEFORE publishing. DO NOT publish as part of a dev/test inner loop. ONLY publish as the FINAL step prior to activating the agent and surfacing it to end users.
+   Test key conversation paths to validate agent behavior when backed by live actions.
+   **CHECKPOINT — Do NOT proceed to Publish unless ALL are true:**
+   - `validate authoring-bundle` passes with zero errors
+   - Live preview (`--use-live-actions`) tested with representative utterances per topic
+   - Traces confirm correct topic routing and action invocation
+   - User explicitly approves deployment
+4. **Publish** — Publish validates metadata structure, not agent behavior. DO NOT publish as part of a dev/test inner loop. ONLY publish as the FINAL step prior to activating the agent and surfacing it to end users.
    `sf agent publish authoring-bundle --json --api-name <Developer_Name>`
    If publish fails, follow *Troubleshooting Publish Failures* in [Metadata & Lifecycle](references/agent-metadata-and-lifecycle.md) before retrying.
 5. **Activate** — Makes new version available to users.
@@ -357,8 +380,8 @@ User wants to create automated tests for Agent Script agent. Involves writing `A
 Read [CLI for Agents](references/salesforce-cli-for-agents.md) for exact command syntax.
 
 1. **Establish coverage baseline** — Read Agent Spec. If no Agent Spec exists, reverse-engineer first by following Comprehend steps. Map every topic, action, and flow control path to identify what needs test coverage.
-2. **Design test scenarios** — For test design methodology, expectations, metrics, test spec YAML format, and templates, use **agentforce-testing** skill. That skill owns all testing content. For each coverage target, write one or more test scenarios: user utterance, expected topic routing, expected action invocations, and expected agent response. Include both happy paths and edge cases.
-3. **Write test spec YAML** — Use template and reference files from **agentforce-testing** skill. Save to `specs/<Agent_API_Name>-testSpec.yaml` in SFDX project.
+2. **Design test scenarios** — For test design methodology, expectations, metrics, test spec YAML format, and templates, use **testing-agentforce** skill. That skill owns all testing content. For each coverage target, write one or more test scenarios: user utterance, expected topic routing, expected action invocations, and expected agent response. Include both happy paths and edge cases.
+3. **Write test spec YAML** — Use template and reference files from **testing-agentforce** skill. Save to `specs/<Agent_API_Name>-testSpec.yaml` in SFDX project.
 4. **Create test metadata** — Generate `AiEvaluationDefinition` from test spec using CLI.
 5. **Deploy test** — Deploy `AiEvaluationDefinition` to org.
 6. **Run tests** — Execute test run using CLI. Capture results.
@@ -373,7 +396,7 @@ Read [CLI for Agents](references/salesforce-cli-for-agents.md) for exact command
    structure for designing meaningful tests
 3. [Design & Agent Spec](references/agent-design-and-spec-creation.md) —
    Agent Spec as test coverage baseline
-4. **agentforce-testing** skill — test spec YAML format, expectations,
+4. **testing-agentforce** skill — test spec YAML format, expectations,
    metrics, test design methodology, and test spec template
 
 ## The Agent Spec
@@ -425,3 +448,73 @@ Planner validates ALL actions across ALL topics at startup. One missing permissi
 
 **Apex action returns empty results in live preview but works in simulated:**
 `WITH USER_MODE` + missing object permissions = silent failure (0 rows, no error). See [Agent User Setup & Permissions](references/agent-user-setup.md), Section 6.2.
+
+## Syntax Quick Reference
+
+- Block order: `system:` → `config:` → `variables:` → `connection:` → `knowledge:` → `language:` → `start_agent topic_selector:` → `topic:` blocks
+- Indentation: **4 spaces** per indent level. Never use tabs. Mixing spaces and tabs breaks the parser.
+- Booleans: `True`/`False` (capitalized)
+- Strings: always double-quoted
+- Numeric action I/O: bare `number` works for variables but **fails at publish** in action I/O. Use `object` + `complex_data_type_name` for numeric action parameters. See [Complex Data Types](references/complex-data-types.md) for the full decision tree.
+- `after_reasoning:` has NO `instructions:` wrapper
+- No `else if` — use compound `if x and y:` or sequential flat ifs
+- Reserved `@InvocableVariable` names: `model`, `description`, `label` — cannot be used as Apex parameter names
+- `@inputs` and `@outputs` are ephemeral: `@inputs` only in `with`; `@outputs` only in `set`/`if` immediately after the action. `@inputs` in `set` = silent failure.
+
+See [Complex Data Types](references/complex-data-types.md) for the full Lightning type mapping decision tree. See [Instruction Resolution](references/instruction-resolution.md) for the 3-phase runtime model.
+
+## Architecture Patterns
+
+Three primary FSM patterns. Full details with code in [Architecture Patterns](references/architecture-patterns.md).
+
+- **Hub-and-Spoke** (most common): `start_agent` routes to specialized topics. Each topic has "back to hub" transition. Do NOT create a separate routing topic.
+- **Verification Gate**: Identity verification before protected topics. `available when` guards on protected transitions.
+- **Post-Action Loop**: Post-action checks at TOP of `instructions: ->` trigger on re-resolution after action completes.
+
+## Scoring Rubric
+
+Score every generated agent on 100 points across 7 categories: Structure (15), Safety (15), Deterministic Logic (20), Instruction Resolution (20), FSM Architecture (10), Action Configuration (10), Deployment Readiness (10).
+
+See [Scoring Rubric](references/scoring-rubric.md) for the complete rubric.
+
+## Review Mode
+
+When user provides an existing `.agent` file (e.g., `review path/to/file.agent`):
+
+1. Read the file
+2. Score against the 100-point rubric
+3. List every issue grouped by category
+4. Provide corrected code snippets
+5. Offer to apply fixes
+
+## Safety Review
+
+7-category LLM-driven safety review for `.agent` files. Integrated into Phase 0 of authoring and deployment. Categories: Identity & Transparency, User Safety, Data Handling, Content Safety, Fairness, Deception, Scope & Boundaries.
+
+See [Safety Review](references/safety-review-reference.md) for the complete framework, severity levels, false positive guidance, and adversarial test prompts.
+
+## Discover & Scaffold
+
+Validate action targets exist in org and generate stubs for missing ones.
+
+See [Discover Reference](references/discover-reference.md) and [Scaffold Reference](references/scaffold-reference.md).
+
+**CRITICAL:** Stubs must return realistic data, not `'TODO'`. Placeholder responses cause SMALL_TALK grounding because the LLM falls back to training data.
+
+## Deploy Lifecycle
+
+Validate → deploy metadata → publish bundle → activate. See [Deploy Reference](references/deploy-reference.md) for phases, error recovery, CI/CD, and rollback.
+
+## Template Assets
+
+Ready-to-use `.agent` templates in `assets/agents/` (hello-world, simple-qa, multi-topic, production-faq, order-service, verification-gate). See also `assets/patterns/` for 11+ reusable design patterns and [Examples](references/examples.md) for inline walkthroughs.
+
+## Additional References
+
+| Topic | File |
+|-------|------|
+| Architecture patterns | [architecture-patterns.md](references/architecture-patterns.md) |
+| Type mapping decision tree | [complex-data-types.md](references/complex-data-types.md) |
+| Feature validity by context | [feature-validity.md](references/feature-validity.md) |
+| Instruction resolution model | [instruction-resolution.md](references/instruction-resolution.md) |
+| Complete agent examples | [examples.md](references/examples.md) |

package/skills/{agentforce-development → developing-agentforce}/assets/agents/README.md

@@ -22,8 +22,8 @@ Templates for building complete, deployable agents.
 
 2. Validate and deploy:
    ```bash
-   sf agent validate authoring-bundle --api-name My_Agent --target-org your-org
-   sf agent publish authoring-bundle --api-name My_Agent --target-org your-org
+   sf agent validate authoring-bundle --json --api-name My_Agent --target-org your-org
+   sf agent publish authoring-bundle --json --api-name My_Agent --target-org your-org
    ```
 
 ## Required Blocks

package/skills/developing-agentforce/assets/agents/order-service.agent

@@ -0,0 +1,272 @@
+# Order Service Agent
+# ========================
+#
+# A complex real-world agent for e-commerce customer service featuring:
+# - Verification gate before order access
+# - Multiple specialized topics (order status, tracking, returns)
+# - Two-level action system with Flow targets
+# - after_reasoning for post-action routing
+# - available when guards for conditional action visibility
+
+system:
+	instructions: |
+		You are an AI Customer Service Assistant helping customers with their orders.
+		Be helpful, empathetic, and efficient in resolving order-related issues.
+		Always verify customer identity before sharing order details.
+		Do not fabricate data — always use action results.
+	messages:
+		welcome: "Hello! I'm here to help you with your orders. How can I assist you today?"
+		error: "I apologize for the inconvenience. Let me try a different approach."
+
+config:
+	developer_name: "OrderServiceAgent"
+	agent_label: "Order Service Assistant"
+	description: "Helps customers check order status, process returns, and track shipments"
+	default_agent_user: "einsteinagent@00dxx000001234.ext"
+
+variables:
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+		visibility: "External"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+		visibility: "External"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+		visibility: "External"
+	customer_email: mutable string = ""
+		description: "Customer email for verification"
+	customer_verified: mutable boolean = False
+		description: "Whether customer identity has been verified"
+	order_number: mutable string = ""
+		description: "Current order number"
+	order_status: mutable string = ""
+		description: "Current order status"
+	tracking_number: mutable string = ""
+		description: "Shipment tracking number"
+	return_reason: mutable string = ""
+		description: "Reason for return"
+	return_initiated: mutable boolean = False
+		description: "Whether a return has been initiated"
+	return_label_url: mutable string = ""
+		description: "URL for return shipping label"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	description: "Route customers through verification then to the right topic"
+	reasoning:
+		instructions: |
+			You are a router only. Do NOT answer questions or provide help directly.
+			Route all users to identity verification first.
+			If already verified, route to the appropriate topic:
+			- Order questions -> use to_orders
+			- Returns -> use to_returns
+			- Tracking -> use to_tracking
+		actions:
+			to_verify: @utils.transition to @topic.verification
+				description: "Begin identity verification"
+			to_orders: @utils.transition to @topic.order_status
+				description: "Check order status"
+				available when @variables.customer_verified == True
+			to_returns: @utils.transition to @topic.returns
+				description: "Process a return"
+				available when @variables.customer_verified == True
+			to_tracking: @utils.transition to @topic.shipment_tracking
+				description: "Track a shipment"
+				available when @variables.customer_verified == True
+
+topic verification:
+	label: "Identity Verification"
+	description: "Verify customer identity before accessing order information"
+
+	actions:
+		verify_customer:
+			description: "Verify customer identity by email"
+			target: "flow://Verify_Customer_Identity"
+			inputs:
+				email: string
+					description: "Customer email address"
+			outputs:
+				verified: boolean
+					description: "Whether verification succeeded"
+				customer_name: string
+					description: "Verified customer name"
+
+	reasoning:
+		instructions: ->
+			if @variables.customer_verified == True:
+				| Welcome back! How can I help you today?
+
+			if @variables.customer_verified == False:
+				| To help you with your order, I need to verify your identity.
+				| What is the email address associated with your account?
+
+		actions:
+			verify: @actions.verify_customer
+				description: "Verify customer identity by email"
+				with email = ...
+				set @variables.customer_verified = @outputs.verified
+				set @variables.customer_email = @outputs.customer_name
+
+			proceed_to_orders: @utils.transition to @topic.order_status
+				description: "Move to order lookup"
+				available when @variables.customer_verified == True
+
+			escalate_now: @utils.escalate
+				description: "Transfer to human agent"
+
+topic order_status:
+	label: "Order Status"
+	description: "Look up order details and provide status updates"
+
+	actions:
+		lookup_order:
+			description: "Look up order by order number"
+			target: "flow://Lookup_Order"
+			inputs:
+				order_number: string
+					description: "Order number to look up"
+				customer_email: string
+					description: "Customer email for validation"
+			outputs:
+				status: string
+					description: "Order status"
+					is_displayable: True
+				tracking_number: string
+					description: "Shipment tracking number"
+					is_displayable: True
+				estimated_delivery: string
+					description: "Estimated delivery date"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			if @variables.order_status != "":
+				| Order {!@variables.order_number} status: {!@variables.order_status}
+				| Would you like to track your shipment or initiate a return?
+
+			if @variables.order_status == "":
+				| What is your order number? You can find it in your confirmation email.
+				| Use the find_order action to look up order details.
+
+		actions:
+			find_order: @actions.lookup_order
+				description: "Look up order details"
+				with order_number = ...
+				with customer_email = @variables.customer_email
+				set @variables.order_status = @outputs.status
+				set @variables.tracking_number = @outputs.tracking_number
+
+			to_returns: @utils.transition to @topic.returns
+				description: "Start a return"
+				available when @variables.order_status != ""
+
+			to_tracking: @utils.transition to @topic.shipment_tracking
+				description: "Track shipment"
+				available when @variables.tracking_number != ""
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+topic shipment_tracking:
+	label: "Shipment Tracking"
+	description: "Track shipment status and estimated delivery"
+
+	actions:
+		get_tracking_details:
+			description: "Get detailed tracking information"
+			target: "flow://Get_Tracking_Details"
+			inputs:
+				tracking_number: string
+					description: "Shipment tracking number"
+			outputs:
+				current_location: string
+					description: "Current package location"
+					is_displayable: True
+				estimated_delivery: string
+					description: "Estimated delivery date"
+					is_displayable: True
+				delivery_status: string
+					description: "Delivery status"
+					is_displayable: True
+
+	reasoning:
+		instructions: |
+			Look up the tracking information for the customer's shipment.
+			Use the track action with the tracking number.
+			Do not fabricate tracking details — always use the action result.
+
+		actions:
+			track: @actions.get_tracking_details
+				description: "Get tracking details"
+				with tracking_number = @variables.tracking_number
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+topic returns:
+	label: "Returns"
+	description: "Process return requests and generate return labels"
+
+	actions:
+		initiate_return:
+			description: "Initiate a return for an order"
+			target: "flow://Initiate_Return"
+			inputs:
+				order_number: string
+					description: "Order number to return"
+				reason: string
+					description: "Reason for return"
+			outputs:
+				return_label_url: string
+					description: "URL for return shipping label"
+					is_displayable: True
+				return_deadline: string
+					description: "Deadline to ship return"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			if @variables.return_initiated == True:
+				| Your return has been initiated!
+				| Return label: {!@variables.return_label_url}
+
+			if @variables.return_initiated == False:
+				| I can help you with a return for order {!@variables.order_number}.
+				| What is the reason for your return?
+				| Use the process_return action to start the return.
+
+		actions:
+			process_return: @actions.initiate_return
+				description: "Process the return request"
+				with order_number = @variables.order_number
+				with reason = ...
+				set @variables.return_initiated = True
+				set @variables.return_label_url = @outputs.return_label_url
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+	after_reasoning: ->
+		if @variables.return_initiated == True:
+			transition to @topic.follow_up
+
+topic follow_up:
+	label: "Follow Up"
+	description: "Handle follow-up actions and next steps"
+	reasoning:
+		instructions: |
+			The customer's request has been processed.
+			Ask if there is anything else you can help with.
+		actions:
+			new_order: @utils.transition to @topic.order_status
+				description: "Look up another order"
+			back: @utils.transition to @topic.topic_selector
+				description: "Start over"