@salesforce/afv-skills 1.7.2 → 1.7.4

package/skills/developing-agentforce/references/production-gotchas.md

@@ -22,13 +22,13 @@ The `before_reasoning:` and `after_reasoning:` lifecycle hooks are validated. Co
 
 ### Cost Optimization Pattern
 
-Fetch data once in `before_reasoning:`, cache in variables, reuse across topics.
+Fetch data once in `before_reasoning:`, cache in variables, reuse across subagents.
 
 ## Lifecycle Hooks
 
 ```yaml
-topic main:
-   description: "Topic with lifecycle hooks"
+subagent main:
+   description: "Subagent with lifecycle hooks"
 
    # BEFORE: Runs deterministically BEFORE LLM sees instructions
    before_reasoning:
@@ -55,7 +55,7 @@ topic main:
 - Reliable primitives: `set`, `if`/`else`, `transition to`. `run` has inconsistent runtime behavior across bundle types — use it in `reasoning.actions:` or `instructions: ->` instead
 - `before_reasoning:` is FREE (no credit cost) - use for data prep
 - `after_reasoning:` is FREE (no credit cost) - use for logging, cleanup
-- `transition to` works in `after_reasoning:` — but if a topic transitions mid-reasoning, the original topic's `after_reasoning:` does NOT run
+- `transition to` works in `after_reasoning:` — but if a subagent transitions mid-reasoning, the original subagent's `after_reasoning:` does NOT run
 
 **❌ WRONG Syntax (causes compile error):**
 ```yaml
@@ -74,19 +74,19 @@ before_reasoning:
 
 | Term | Syntax | Behavior | Use When |
 |------|--------|----------|----------|
-| **Handoff** | `@utils.transition to @topic.X` | Control transfers completely, child generates final response | Checkout, escalation, terminal states |
-| **Supervision** | `@topic.X` (as action reference) | Parent orchestrates, child returns, parent synthesizes | Expert consultation, sub-tasks |
+| **Handoff** | `@utils.transition to @subagent.X` | Control transfers completely, child generates final response | Checkout, escalation, terminal states |
+| **Supervision** | `@subagent.X` (as action reference) | Parent orchestrates, child returns, parent synthesizes | Expert consultation, sub-tasks |
 
 ```yaml
-# HANDOFF - child topic takes over completely:
-checkout: @utils.transition to @topic.order_checkout
+# HANDOFF - child subagent takes over completely:
+checkout: @utils.transition to @subagent.order_checkout
    description: "Proceed to checkout"
-# → @topic.order_checkout generates the user-facing response
+# → @subagent.order_checkout generates the user-facing response
 
 # SUPERVISION - parent remains in control:
-get_advice: @topic.product_expert
+get_advice: @subagent.product_expert
    description: "Consult product expert"
-# → @topic.product_expert returns, parent topic synthesizes final response
+# → @subagent.product_expert returns, parent subagent synthesizes final response
 ```
 
 **KNOWN BUG**: Adding ANY new action in Canvas view may inadvertently change Supervision references to Handoff transitions.
@@ -111,16 +111,16 @@ outputs:
       is_used_by_planner: True    # LLM can use for routing decisions
 
 # In Agent Script - LLM routes but cannot hallucinate:
-topic intent_router:
+subagent intent_router:
    reasoning:
       instructions: ->
          run @actions.classify_intent
          set @variables.intent = @outputs.intent_classification
 
          if @variables.intent == "refund":
-            transition to @topic.refunds
+            transition to @subagent.refunds
          if @variables.intent == "order_status":
-            transition to @topic.orders
+            transition to @subagent.orders
 ```
 
 ## Action I/O Metadata Properties
@@ -187,26 +187,26 @@ KNOWN BUG: Chained actions with Prompt Templates don't properly map inputs using
 
 For prompt template action definitions, input binding syntax, and grounded data patterns, see [Action Prompt Templates](action-prompt-templates.md).
 
-## Latch Variable Pattern for Topic Re-entry
+## Latch Variable Pattern for Subagent Re-entry
 
-Topic selector doesn't properly re-evaluate after user provides missing input. Use a "latch" variable to force re-entry:
+Subagent router doesn't properly re-evaluate after user provides missing input. Use a "latch" variable to force re-entry:
 
 ```yaml
 variables:
    verification_in_progress: mutable boolean = False
 
-start_agent topic_selector:
+start_agent agent_router:
    reasoning:
       instructions: ->
          if @variables.verification_in_progress == True:
-            transition to @topic.verification
+            transition to @subagent.verification
          | How can I help you today?
       actions:
-         start_verify: @topic.verification
+         start_verify: @subagent.verification
             description: "Start identity verification"
             set @variables.verification_in_progress = True
 
-topic verification:
+subagent verification:
    reasoning:
       instructions: ->
          | Please provide your email to verify your identity.
@@ -219,9 +219,9 @@ topic verification:
 
 ## Loop Protection Guardrail
 
-Agent Scripts have a built-in guardrail that limits iterations to approximately **3-4 loops** before breaking out and returning to the Topic Selector.
+Agent Scripts have a built-in guardrail that limits iterations to approximately **3-4 loops** before breaking out and returning to the Subagent Router.
 
-**Best Practice**: Map out your execution paths and test for unintended circular references between topics.
+**Best Practice**: Map out your execution paths and test for unintended circular references between subagents.
 
 ## Token & Size Limits
 

package/skills/developing-agentforce/references/safety-review-reference.md

@@ -78,8 +78,8 @@ For each finding, assign severity: **BLOCK** (stops pipeline), **WARN** (flags f
 | Check | Severity | What to Look For |
 |-------|----------|------------------|
 | Missing scope definition | WARN | No "do not" or "only handle" clause |
-| Overly broad scope | WARN | No topic boundaries, no escalation path |
-| Missing escalation | WARN | Complex/sensitive topics without human transfer |
+| Overly broad scope | WARN | No subagent boundaries, no escalation path |
+| Missing escalation | WARN | Complex/sensitive subagents without human transfer |
 | Missing error handling | INFO | No instructions for when agent can't help |
 
 ## Output Format

package/skills/developing-agentforce/references/scoring-rubric.md

@@ -6,11 +6,11 @@ Score every generated agent against this rubric before presenting to the user.
 
 | Category | Points | Key Criteria |
 |----------|--------|--------------|
-| Structure & Syntax | 15 | All required blocks present (`system`, `config`, `start_agent`, at least one `topic`). Correct block order (`system` → `config` → `variables` → ...). Proper nesting. Consistent 4-space indentation. Valid field names. All string values double-quoted. |
+| Structure & Syntax | 15 | All required blocks present (`system`, `config`, `start_agent`, at least one `subagent`). Correct block order (`system` → `config` → `variables` → ...). Proper nesting. Consistent 4-space indentation. Valid field names. All string values double-quoted. |
 | Safety & Responsible AI | 15 | Evaluated via safety review (7 categories): AI disclosure present, no impersonation/deception/manipulation, responsible data handling, no harmful content (including euphemisms), no discrimination (direct or proxy), clear scope boundaries, escalation paths for sensitive topics. Deduct 15 for any BLOCK finding, 5 per WARN finding. |
-| Deterministic Logic | 20 | `after_reasoning` patterns for post-action routing. FSM transitions with no dead-end topics. `available when` guards for security-sensitive actions. Post-action checks at TOP of `instructions: ->`. |
+| Deterministic Logic | 20 | `after_reasoning` patterns for post-action routing. FSM transitions with no dead-end subagents. `available when` guards for security-sensitive actions. Post-action checks at TOP of `instructions: ->`. |
 | Instruction Resolution | 20 | Clear, actionable instructions. Procedural mode (`->`) where conditionals are needed. Literal mode (`\|`) where static text suffices. Variable injection where dynamic. Conditional instructions based on state. |
-| FSM Architecture | 10 | Hub-and-spoke or verification gate pattern. Every topic reachable. Every topic has an exit (transition or escalation). No orphan topics. Start topic routes correctly. |
+| FSM Architecture | 10 | Hub-and-spoke or verification gate pattern. Every subagent reachable. Every subagent has an exit (transition or escalation). No orphan subagents. Start subagent routes correctly. |
 | Action Configuration | 10 | Proper Level 1 definitions with targets and I/O schemas. Correct Level 2 invocations with `with`/`set`. Slot-filling (`...`) for conversational inputs. Output capture into variables. Correct type mapping for action I/O (use `object` + `complex_data_type_name` for SObjects and custom Lightning types). |
 | Deployment Readiness | 10 | Valid `default_agent_user`. `developer_name` matches folder. `bundle-meta.xml` present with `<bundleType>AGENT</bundleType>`. Linked variables for service agents (`EndUserId`, `RoutableId`, `ContactId`). |
 

package/skills/generating-custom-lightning-type/SKILL.md

@@ -20,6 +20,7 @@ Use this skill when you need to:
 Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the Lightning Platform (including Einstein Agent actions) to describe structured inputs/outputs and drive editor/renderer experiences.
 
 ## Configuration
+- **Choose referenced CLT pattern for nested objects** - When you need a **reusable** or **separately deployed** nested type, create a CLT for that shape and reference it with `"lightning:type": "c__<CLTName>"`. That string is the referenced type’s **`lightning:type` value / FQN / registered identifier** — not the JSON Schema `title`.
 - **Choose standard Lightning types** when the structure is simple and can be expressed with properties and supported primitive `lightning:type` identifiers.
 - **Choose Apex class types** (`@apexClassType/...`) when the structure already exists server-side and you want the Apex class to define the shape.
 - **Include editor/renderer config** only when you need custom UI behavior (custom LWC input/output components). Otherwise, omit.
@@ -33,7 +34,7 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - `"unevaluatedProperties"` is enforced as `false` by the CLT metaschema. Do not set it to `true`.
 - **Root object schemas MUST NOT include** `"examples"` when `"unevaluatedProperties": false` is set.
 - **Nested objects (inside `properties`) MUST NOT set** `"lightning:type": "lightning__objectType"`.
-  - Nested objects should be plain JSON Schema objects (`type`, `properties`, optional `required`, optional `unevaluatedProperties`).
+    - Nested objects can be: references to other CLTs using `c__<CLTName>` syntax.
 - **List/array properties are highly restricted by the CLT metaschema**:
   - **CRITICAL LIMITATION**: the CLT metaschema may reject the `items` keyword entirely. Treat `items` as **disallowed by default**.
   - **Root-level arrays** (direct children of the root `properties`):
@@ -96,8 +97,13 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 2. **Draft `schema.json`**
    - Start with the root object structure (required root fields).
    - Add `properties` using valid primitive `lightning:type` identifiers.
-   - For nested objects: omit `lightning:type` and keep keywords minimal.
+   - For nested-object properties, use **CLT Reference pattern**:
+     - `"lightning:type": "c__<CLTName>"` to reference another CLT
+     - The referenced CLT must be deployed to the org before the parent CLT.
+   - For Apex-based nested objects: Use `@apexClassType/...` when structure exists server-side.
+   - If the prompt explicitly requires true nested object output, prefer an **Apex-based CLT** (`@apexClassType/...`) for deploy-safe nested structures.
    - For arrays: follow the strict list rules (avoid `items`; avoid `lightning:type` on nested arrays).
+   - Before deployment, verify exact `lightning:type` spellings (for example, use `lightning__richTextType`, not misspelled variants).
 3. **(Optional) Draft `editor.json`** (only if custom UI is required)
    - **Supported shape:** Top-level `editor` object with `editor.componentOverrides` and `editor.layout`.
      - Top-level `editor` object.
@@ -159,6 +165,7 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
      </LightningComponentBundle>
      ```
 7. **Deploy and validate**
+   - Run a final schema sanity check before deploy: valid `lightning:type` names, required fields present, and no disallowed keywords.
    - Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles.
    - Validate incrementally: if deployment fails, remove disallowed keywords first (especially `examples`, `items`, nested `lightning:type`).
 
@@ -166,7 +173,9 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 | Error / Symptom | Likely Cause | Fix |
 |---|---|---|
 | Schema validation fails due to unknown keyword | `unevaluatedProperties: false` + disallowed keyword (commonly `examples`, `items`) | Remove the offending keyword; keep schema minimal |
-| Nested object validation failure | Nested object includes `lightning:type: lightning__objectType` | Remove `lightning:type` from nested objects |
+| Nested object validation failure | Org/channel validation rejects nested object typing in `LightningTypeBundle` | Use CLT reference (`c__<CLTName>`) or Apex class types |
+| Invalid CLT reference | Referenced CLT doesn't exist in org or incorrect syntax | Deploy the referenced CLT first; `c__<CLTName>` must match the referenced type’s **`lightning:type` value / FQN / registered identifier**, not `title` |
+| Invalid or misspelled `lightning:type` (for example, `lightning__richtextType` instead of `lightning__richTextType`) | Incorrect generated type name | Cross-check all `lightning:type` values against supported type names and correct them before deployment |
 | Array property rejected | Use of `items` (or `lightning:type` in nested arrays) rejected by validator | For nested arrays: keep only `type: "array"`. For root arrays: use minimal structure; remove `items` if rejected |
 | Apex-based CLT rejected | Extra fields added (e.g., `type`, `properties`) | Use only `title`, optional `description`, and `lightning:type` |
 | Editor config rejected | Use of invalid patterns (`es_property_editors/inputList`, `itemSchema`) or unrecognized top-level keys | Use `editor.componentOverrides` and `editor.layout`; keep config minimal |

package/skills/observing-agentforce/SKILL.md

@@ -99,8 +99,8 @@ fi
 Read the `.agent` file and verify it has proper Agent Script structure:
 - `system:` block with `instructions:`
 - `config:` block with `developer_name:`
-- `start_agent` or `topic` blocks with `reasoning: instructions:`
-- Each topic should have distinct `instructions:` content (not identical across topics)
+- `start_agent` or `subagent` blocks with `reasoning: instructions:`
+- Each subagent should have distinct `instructions:` content (not identical across subagents)
 
 Store the resolved path as `AGENT_FILE` for Phase 3.
 
@@ -187,7 +187,7 @@ sf agent test results --json --job-id "$JOB_ID" --result-format json -o <org>
 
 ### 1-ALT.2 Derive test utterances from .agent file (if no test suite)
 
-If no test suite exists, derive utterances: one per non-entry topic (from `description:` keywords), one per key action, one guardrail test, one multi-turn test.
+If no test suite exists, derive utterances: one per non-entry subagent (from `description:` keywords), one per key action, one guardrail test, one multi-turn test.
 
 ### 1-ALT.3 Preview with `--authoring-bundle` (local traces)
 
@@ -209,13 +209,13 @@ sf agent preview end --json --session-id "$SESSION_ID" --authoring-bundle <Bundl
 
 | Issue type | Trace command |
 |---|---|
-| Topic misroute | `jq -r '.plan[] \| select(.type=="NodeEntryStateStep") \| .data.agent_name' "$TRACE"` |
+| Subagent misroute | `jq -r '.plan[] \| select(.type=="NodeEntryStateStep") \| .data.agent_name' "$TRACE"` |
 | Action not called | `jq -r '.plan[] \| select(.type=="EnabledToolsStep") \| .data.enabled_tools[]' "$TRACE"` |
 | LOW adherence | `jq -r '.plan[] \| select(.type=="ReasoningStep") \| {category, reason}' "$TRACE"` |
 | Variable capture fail | `jq -r '.plan[] \| select(.type=="VariableUpdateStep") \| .data.variable_updates[]' "$TRACE"` |
 | Vague instructions | `jq -r '.plan[] \| select(.type=="LLMStep") \| .data.messages_sent[0].content' "$TRACE"` |
 
-**DefaultTopic trace quirk:** With `--authoring-bundle`, the root `.topic` field often shows `"DefaultTopic"` even when routing works. Always use `NodeEntryStateStep.data.agent_name` for the real topic chain.
+**DefaultTopic trace quirk:** With `--authoring-bundle`, the root `.topic` field often shows `"DefaultTopic"` even when routing works. Always use `NodeEntryStateStep.data.agent_name` for the real subagent chain.
 
 **Entry answering directly (SMALL_TALK pattern):** If `start_agent` trace shows `SMALL_TALK` grounding and transition tools visible but none invoked, add "You are a router only. Do NOT answer questions directly." to `start_agent` instructions.
 
@@ -271,7 +271,7 @@ Render turn-by-turn timeline from `ConversationData` JSON for each session.
 
 > Full issue pattern table and classification categories: see `references/issue-classification.md`
 
-Check each session for: action errors, topic misroutes, missing actions, wrong inputs, variable capture failures, no transitions, slow actions, LOW adherence, abandoned sessions, dead topics, publish drift, dead hub anti-pattern, entry answering directly, and safety issues.
+Check each session for: action errors, subagent misroutes, missing actions, wrong inputs, variable capture failures, no transitions, slow actions, LOW adherence, abandoned sessions, dead subagents, publish drift, dead hub anti-pattern, entry answering directly, and safety issues.
 
 Priority: P1 = action errors, misroutes, LOW adherence; P2 = missing actions, variable bugs, knowledge gaps; P3 = performance, abandoned sessions.
 
@@ -281,7 +281,7 @@ Present sessions analyzed, issues grouped by root cause category, and uplift est
 
 > Full structural analysis checks, cross-reference procedures, and publish drift detection: see `references/issue-classification.md`
 
-Retrieve the `.agent` file from the org, run automated checks (topic count vs action blocks, dead hub detection, orphan actions, cross-topic variable dependencies), and cross-reference STDM symptoms against the file structure.
+Retrieve the `.agent` file from the org, run automated checks (subagent count vs action blocks, dead hub detection, orphan actions, cross-subagent variable dependencies), and cross-reference STDM symptoms against the file structure.
 
 ---
 
@@ -325,7 +325,7 @@ Map each confirmed issue to a fix location in the `.agent` file (description, in
 
 ### 3.4 Regression prevention
 
-Establish baseline before editing. Make minimal edits. Test immediately after each edit. One fix per publish cycle. Check cross-topic dependencies. Test adjacent topics.
+Establish baseline before editing. Make minimal edits. Test immediately after each edit. One fix per publish cycle. Check cross-subagent dependencies. Test adjacent subagents.
 
 ### 3.5 Apply fixes
 

package/skills/observing-agentforce/apex/AgentforceOptimizeService.cls

@@ -80,7 +80,7 @@ public with sharing class AgentforceOptimizeService {
      */
     public class TurnData {
         public String interaction_id;
-        /** Topic API name — null/mismatch signals a misroute (P1) */
+        /** Subagent API name (stored as `topic` in STDM) — null/mismatch signals a misroute (P1) */
         public String topic;
         public String start_time;
         public String end_time;
@@ -1142,7 +1142,7 @@ public with sharing class AgentforceOptimizeService {
         @InvocableVariable(label='Agent API Name' required=false)
         public String agentApiName;
 
-        @InvocableVariable(label='Topic API Name' required=false)
+        @InvocableVariable(label='Subagent API Name' required=false)
         public String topicApiName;
 
         @InvocableVariable(label='Lookback Days' required=false)

package/skills/observing-agentforce/references/improve-reference.md

@@ -68,17 +68,17 @@ variables:
 
 start_agent: entry_topic
 
-topic entry_topic:
-    label: "Entry Topic"
-    description: "Routes users to specialized topics"
+subagent entry_topic:
+    label: "Entry Subagent"
+    description: "Routes users to specialized subagents"
 
     reasoning:
         instructions: ->
             | Welcome the user warmly.
             | Ask how you can help today.
         actions:
-            go_to_orders: @utils.transition to @topic.orders
-                description: "Route to orders topic"
+            go_to_orders: @utils.transition to @subagent.orders
+                description: "Route to orders subagent"
             check_order: @actions.get_order_status
                 description: "Look up order details"
                 with order_id = @variables.order_id
@@ -86,10 +86,10 @@ topic entry_topic:
 ```
 
 **Critical mapping to Salesforce metadata:**
-- `topic.description` -> `GenAiPluginDefinition.Description` (topic routing signal)
-- `topic.reasoning.instructions` -> `GenAiPluginInstructionDef.Instruction` (verbatim LLM prompt text)
+- `subagent.description` -> `GenAiPluginDefinition.Description` (subagent routing signal)
+- `subagent.reasoning.instructions` -> `GenAiPluginInstructionDef.Instruction` (verbatim LLM prompt text)
 - `system.instructions` -> `GenAiPlannerDefinition.Description` (agent-level system prompt)
-- `reasoning.actions` with `@utils.transition` -> topic transitions
+- `reasoning.actions` with `@utils.transition` -> subagent transitions
 - `reasoning.actions` with `@actions.*` -> action invocations with `with` (input) and `set` (output) bindings
 
 ---
@@ -98,17 +98,17 @@ topic entry_topic:
 
 | Root cause category | STDM signal | Fix target in .agent file | What to change |
 |---|---|---|---|
-| `Agent Configuration Gap` | Topic misroute | `topic <name>: description:` | Tighten description to exclude overlapping intents |
-| `Agent Configuration Gap` | Action not called | `topic <name>: reasoning: actions:` and `reasoning: instructions:` | Add action definition under `actions:` and mention it in `instructions:` |
+| `Agent Configuration Gap` | Subagent misroute | `subagent <name>: description:` | Tighten description to exclude overlapping intents |
+| `Agent Configuration Gap` | Action not called | `subagent <name>: reasoning: actions:` and `reasoning: instructions:` | Add action definition under `actions:` and mention it in `instructions:` |
 | `Agent Configuration Gap` | Wrong action input / error | `reasoning: actions: <action>: with` | Correct `with` bindings or action `target:` URI |
 | `Agent Configuration Gap` | Variable not captured | `reasoning: actions: <action>: set` | Add `set @variables.myVar = @outputs.field` binding |
-| `Agent Configuration Gap` | No post-action transition | `reasoning: actions:` | Add `@utils.transition to @topic.<next_topic>` action |
-| `Agent Configuration Gap` | LOW adherence / vague instructions | `topic <name>: reasoning: instructions:` | Rewrite using instruction principles below |
-| `Agent Configuration Gap` | Identical instructions across topics | All `topic: reasoning: instructions:` blocks | Give each topic distinct, actionable instructions |
-| `Knowledge Gap -- Infrastructure` | Knowledge question answered generically | Add knowledge action definition to the relevant topic | Define action with `retriever://` target |
+| `Agent Configuration Gap` | No post-action transition | `reasoning: actions:` | Add `@utils.transition to @subagent.<next_subagent>` action |
+| `Agent Configuration Gap` | LOW adherence / vague instructions | `subagent <name>: reasoning: instructions:` | Rewrite using instruction principles below |
+| `Agent Configuration Gap` | Identical instructions across subagents | All `subagent: reasoning: instructions:` blocks | Give each subagent distinct, actionable instructions |
+| `Knowledge Gap -- Infrastructure` | Knowledge question answered generically | Add knowledge action definition to the relevant subagent | Define action with `retriever://` target |
 | `Knowledge Gap -- Content` | Knowledge question -- wrong/missing answer | N/A (org data issue) | Add missing articles to knowledge space |
 | `Platform / Runtime Issue` | Action timeout / latency > 10s | Flow or Apex class (not .agent) | Optimize query/processing logic |
-| `Agent Configuration Gap` | Dead hub anti-pattern | Entire intermediate topic block | Move transitions to `start_agent > reasoning > actions:`, delete dead hub topic |
+| `Agent Configuration Gap` | Dead hub anti-pattern | Entire intermediate subagent block | Move transitions to `start_agent > reasoning > actions:`, delete dead hub subagent |
 
 **Target resolution checklist:**
 
@@ -121,20 +121,20 @@ topic entry_topic:
 
 ---
 
-## Principles for Effective Topic Instructions
+## Principles for Effective Subagent Instructions
 
-Good instructions are specific, imperative, and action-named. Poor instructions are persona descriptions or generic guidance reused across topics.
+Good instructions are specific, imperative, and action-named. Poor instructions are persona descriptions or generic guidance reused across subagents.
 
 1. **Name the action explicitly** -- "Use `@actions.schedule_test_drive` to book the appointment" not "help the user book"
 2. **State the pre-condition** -- "Only handle scheduling after the customer's name and email have been collected"
 3. **State what to do after** -- "After scheduling completes, confirm the date/time and transition to follow_up"
-4. **Scope tightly** -- "This topic handles test drive scheduling only. For vehicle specs or pricing, do not answer -- the user should be routed to general_support"
-5. **Keep persona out of instructions** -- persona belongs in `system: instructions:` (agent-level), not per-topic reasoning instructions
-6. **One responsibility per topic** -- if the instruction covers 3 distinct tasks, split into 3 topics
+4. **Scope tightly** -- "This subagent handles test drive scheduling only. For vehicle specs or pricing, do not answer -- the user should be routed to general_support"
+5. **Keep persona out of instructions** -- persona belongs in `system: instructions:` (agent-level), not per-subagent reasoning instructions
+6. **One responsibility per subagent** -- if the instruction covers 3 distinct tasks, split into 3 subagents
 
 **Before / after example** (identical instructions -> distinct instructions):
 
-*Before (generic persona text, same across all topics):*
+*Before (generic persona text, same across all subagents):*
 ```
 reasoning:
     instructions: |
@@ -142,7 +142,7 @@ reasoning:
         help them with their needs, and guide them toward scheduling a test drive.
 ```
 
-*After (for `identity_collection` topic specifically):*
+*After (for `identity_collection` subagent specifically):*
 ```
 reasoning:
     instructions: ->
@@ -154,7 +154,7 @@ reasoning:
             description: "Capture customer contact details"
             set @variables.customer_name = @outputs.name
             set @variables.customer_email = @outputs.email
-        proceed: @utils.transition to @topic.schedule_test_drive
+        proceed: @utils.transition to @subagent.schedule_test_drive
             description: "Move to test drive scheduling after info collected"
             available when @variables.customer_name != ""
 ```
@@ -163,7 +163,7 @@ reasoning:
 
 ## Regression Prevention
 
-When editing topic instructions, follow these principles:
+When editing subagent instructions, follow these principles:
 
 1. **Establish a baseline BEFORE editing** -- Run the test utterance 3 times before making changes. Record the pass rate.
 
@@ -172,35 +172,35 @@ When editing topic instructions, follow these principles:
 3. **Avoid instruction expansion** -- Adding more text to instructions does NOT always help. Prefer:
    - Adding a single action reference: "Use `@actions.X` to look up..."
    - Adding a single constraint: "Do not proceed until the customer provides..."
-   - Adding a single routing directive: "After completing, transition to @topic.Y"
+   - Adding a single routing directive: "After completing, transition to @subagent.Y"
 
 4. **Test immediately after each edit** -- Run the same test utterances. If pass rate drops, revert the change immediately.
 
 5. **One fix per publish cycle** -- Do not batch multiple instruction changes into a single publish.
 
-6. **Check cross-topic dependencies before editing** -- Before changing Topic A, identify variable dependencies, transition chains, and shared variable mutations:
+6. **Check cross-subagent dependencies before editing** -- Before changing Subagent A, identify variable dependencies, transition chains, and shared variable mutations:
    ```bash
    grep -n 'set @variables\.' "$AGENT_FILE"
    grep -n 'with .* = @variables\.' "$AGENT_FILE"
-   grep -n '@utils.transition to @topic\.' "$AGENT_FILE"
+   grep -n '@utils.transition to @subagent\.' "$AGENT_FILE"
    ```
 
-7. **Test adjacent topics after each fix** -- Include at least one cross-topic test to confirm the fix didn't cause spillover routing.
+7. **Test adjacent subagents after each fix** -- Include at least one cross-subagent test to confirm the fix didn't cause spillover routing.
 
-8. **Verify start_agent routing after topic removal** -- If removing a dead hub or merging topics, verify `start_agent > reasoning > actions:` still has transition actions to all remaining topics.
+8. **Verify start_agent routing after subagent removal** -- If removing a dead hub or merging subagents, verify `start_agent > reasoning > actions:` still has transition actions to all remaining subagents.
 
 ---
 
 ## Apply Fixes
 
-**Step 1 -- Read the current .agent file** using the Read tool. Locate the specific `topic` block that needs changes.
+**Step 1 -- Read the current .agent file** using the Read tool. Locate the specific `subagent` block that needs changes.
 
 **Step 2 -- Edit the .agent file directly** using the Edit tool. Edit only the specific lines that need to change. Common edit patterns:
 
-- **Topic description** (for misroute fixes): Change `description:` text
-- **Topic instructions** (for LOW adherence): Replace `reasoning: instructions:` block
+- **Subagent description** (for misroute fixes): Change `description:` text
+- **Subagent instructions** (for LOW adherence): Replace `reasoning: instructions:` block
 - **Adding an action**: Add definition under `reasoning: actions:`
-- **Adding a transition**: Add `@utils.transition to @topic.<name>` action
+- **Adding a transition**: Add `@utils.transition to @subagent.<name>` action
 - **Adding an `available when` guard**: Add guard condition to action definition
 
 IMPORTANT: Agent Script uses **tabs** for indentation, not spaces.
@@ -238,7 +238,7 @@ sf project deploy start --json --metadata "AiAuthoringBundle:<AGENT_API_NAME>" -
 sf agent activate --json --api-name <AGENT_API_NAME> -o <org>
 ```
 
-> **Warning: deploy + activate is an incomplete fallback.** `sf project deploy start` stores the bundle metadata but does **NOT** propagate topic-level `reasoning: actions:` blocks to live `GenAiPluginDefinition` records. Always verify with `--authoring-bundle` preview.
+> **Warning: deploy + activate is an incomplete fallback.** `sf project deploy start` stores the bundle metadata but does **NOT** propagate subagent-level `reasoning: actions:` blocks to live `GenAiPluginDefinition` records. Always verify with `--authoring-bundle` preview.
 
 **Never use the Tooling API to patch `GenAiPluginInstructionDef` or other BPO objects directly.**
 
@@ -266,7 +266,7 @@ sf agent preview end --json --session-id "$SESSION_ID" --authoring-bundle <Bundl
 
 **Trace-based verification checklist:**
 ```bash
-# 1. Correct topic routing
+# 1. Correct subagent routing
 jq -r '.topic' "$TRACE"
 # 2. Grounding passed (no UNGROUNDED)
 jq -r '.plan[] | select(.type == "ReasoningStep") | .category' "$TRACE"
@@ -282,7 +282,7 @@ jq -r '.plan[] | select(.type == "VariableUpdateStep") | .data.variable_updates[
 
 | Metric | What to look for after fix |
 |---|---|
-| Topics seen in STDM | Dead topics should now appear in session data |
+| Subagents seen in STDM | Dead subagents should now appear in session data |
 | `TRUST_GUARDRAILS_STEP` value | `LOW` occurrences should drop or disappear |
 | Action invocation per turn | Actions should now fire for the intents they cover |
 | `action_error_count` | Should not increase (regression check) |
@@ -295,7 +295,7 @@ jq -r '.plan[] | select(.type == "VariableUpdateStep") | .data.variable_updates[
 After applying fixes, re-run safety review on the modified `.agent` file. Optimization fixes can inadvertently introduce safety regressions:
 
 - Relaxing `available when` guards may expose actions that should be gated
-- Expanding topic descriptions may cause the agent to handle out-of-scope requests
+- Expanding subagent descriptions may cause the agent to handle out-of-scope requests
 - Changing instructions to be more permissive may weaken guardrails
 - Adding literal instructions with tool names may bypass safety boundaries
 
@@ -304,7 +304,7 @@ After applying fixes, re-run safety review on the modified `.agent` file. Optimi
 1. **Scope boundaries** -- Did the fix widen the agent's scope beyond what's appropriate?
 2. **Guard conditions** -- Did relaxing `available when` expose sensitive actions?
 3. **Instruction safety** -- Do new/modified instructions maintain appropriate guardrails?
-4. **Escalation paths** -- Are escalation paths still intact after topic restructuring?
+4. **Escalation paths** -- Are escalation paths still intact after subagent restructuring?
 
 **If any new BLOCK finding is introduced by the fix:** revert and find an alternative fix. Do NOT deploy an agent with new safety violations.
 
@@ -322,12 +322,12 @@ subjectName: <AgentApiName>
 
 testCases:
   - utterance: "<exact utterance from Phase 2 scenario>"
-    expectedTopic: <topic_that_should_handle_this>
+    expectedTopic: <subagent_that_should_handle_this>
     expectedActions:
       - <action_that_should_fire>
 
   - utterance: "<another failing utterance>"
-    expectedTopic: <expected_topic>
+    expectedTopic: <expected_subagent>
     expectedOutcome: "Agent should <expected behavior description>"
 ```