@salesforce/afv-skills 1.48.0 → 1.50.0

package/skills/field-service-scheduling-policy-designer-query/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: field-service-scheduling-policy-designer-query
+description: "Designs the four policy-level settings for a Salesforce Field Service scheduling policy — name, optimization mode (In-Day vs Global), commit mode, and description — and delegates to work rule design when complete. Use this skill when a user wants to design, configure, or set up a Field Service scheduling policy's policy-level settings."
+user-invocable: false
+metadata:
+  version: "1.0"
+  domains: ["Field Service"]
+---
+
+# Salesforce Field Service – Scheduling Policy Designer
+
+**Entry point for the scheduling policy design flow.** This skill collects the four policy-level settings that define the scheduling policy itself, then hands off to the work rule design phase.
+
+**Interview sequence (REQUIRED):** Complete each step fully before moving to the next — do not skip ahead:
+1. **Scheduling Policy** — collect name, optimization mode, commit mode, description
+2. **Work Rule Design** (`sfs-work-rule-designer`) — define eligibility filters, one question at a time
+3. **Service Objective Design** (`sfs-service-objective-designer`) — define scoring weights via trade-off interview
+4. **Record creation** (`sfs-sobject-create`) — creates all Salesforce records from the finalized design
+
+This skill covers step 1 only. It does not configure work rules, service objectives, or create any Salesforce records.
+
+---
+
+## Entry point
+
+Run the full interview in order: name, optimization mode, commit mode, description.
+
+Never expose internal skill names, SOR IDs, or tool references to the user.
+
+---
+
+## What is a scheduling policy?
+
+A **scheduling policy** is the rulebook and scoring guide the Field Service optimizer uses to schedule appointments. Every policy bundles two things together:
+
+- **Work rules** — hard filters that eliminate candidates who don't qualify (wrong skills, unavailable, outside territory). Designed in step 2.
+- **Service objectives** — soft scoring that ranks qualified candidates (minimize travel, schedule ASAP, prefer a specific technician). Designed in step 3.
+
+The four settings collected here define the policy container itself: its name, how the optimizer runs, and what happens when a conflict occurs mid-run.
+
+**Starting points:** Salesforce ships four standard starter policies — Customer First, High Intensity, Soft Boundaries, Emergency. This is background knowledge only — never offer or suggest these to the user. Every policy this skill designs is built fresh from the user's own requirements.
+
+---
+
+## When to use
+
+- Starting a new scheduling policy from scratch
+- When a user mentions a scheduling policy, optimization mode, In-Day Optimization, or Commit Mode
+- As the first step in the full scheduling policy design flow before work rules or objectives are discussed
+
+---
+
+## Design principles
+
+1. **Ask one setting at a time** — wait for the user's answer before moving to the next. Do not bundle questions.
+
+2. **Lead with a recommendation when context supports it** — for Optimization Mode and Commit Mode, suggest the best-fit option based on what the user has described. A ranked steer, not a flat menu. Omit when confidence is low.
+
+3. **Question format** (two or three parts):
+   ```markdown
+   **Recommendation:** [Only for Optimization Mode and Commit Mode, when context is sufficient. Omit otherwise.]
+
+   **Question:** [The actual question]
+
+   **Why it matters:** [1–2 sentences on why this setting exists and how it affects scheduling]
+   ```
+
+---
+
+## Core settings
+
+Ask about each setting **in this order**:
+
+- **Scheduling Policy Name** — the display name for the policy. Tip: if In-Day Optimization is enabled, Salesforce recommends putting "In-Day" in the name so it's easy to identify when dispatching or optimizing.
+
+- **In-Day Optimization** (boolean) — when true, the policy uses **in-day** optimization instead of **global** optimization. Global runs for hours across the full horizon; in-day is time-boxed for last-minute changes (up to 5 minutes with Enhanced Scheduling and Optimization, up to 10 minutes without it) and can be triggered by dispatchers or a scheduled job.
+
+- **Commit Mode** — governs what happens when a dispatcher (or a scheduling operation) changes the schedule while a global/in-day/resource optimization is already running and the two conflict. Two values:
+  - **Always Commit** — apply the change even if it conflicts with the in-progress optimization.
+  - **Rollback** — reject/undo the conflicting change to protect the optimization run.
+
+- **Description** — a free-text description of the policy's intent. After the first three settings are answered, generate a suggested description from those answers and ask the user to confirm or adjust it. Good place to record the "Policy at a Glance" summary this design flow generates in step 3.
+
+---
+
+## Output
+
+Once all four settings are confirmed, show a plain-English summary:
+
+> **Policy settings confirmed:**
+> - **Name:** [name]
+> - **Mode:** [In-Day Optimization (up to 5 min) | Global Optimization (runs for hours)]
+> - **Commit Mode:** [Always Commit | Rollback]
+> - **Description:** [description]
+>
+> Ready to move on to work rule design?
+
+The `policy` block carried forward to the next step:
+
+```json
+{
+  "policy": {
+    "name": "<policy name>",
+    "inDayOptimization": true | false,
+    "commitMode": "Always Commit" | "Rollback",
+    "description": "<description>"
+  }
+}
+```
+
+---
+
+## Handoff
+
+When the user confirms, delegate to `sfs-work-rule-designer`. Pass the `policy` block as context — the work rule designer needs the policy name to correctly name each rule.
+
+Do not start the work rule interview here. Transition message:
+
+> "Policy settings are set. Next: work rules — the filters that determine which resources and time slots are eligible for an appointment. I'll walk through this one question at a time."
+
+**Note:** The work rule designer always includes exactly one **Service Resource Availability** rule (mandatory for every policy). No need to ask about it here.

package/skills/field-service-setup-orchestrator-get/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: field-service-setup-orchestrator-get
+description: "Use this skill to set up Salesforce Field Service — Work Types, Skills, Service Territories, Operating Hours, Scheduling Policy, Work Rules, Service Objectives, Data Capture Forms, FSL mobile forms, Pre-Work Brief, Mobile Branding, or any FSL setup, enablement, or configuration request. Entry point that identifies what the user wants to configure and routes to the right sub-workflow: Foundation Setup, Scheduling Policy, Data Capture Forms, Pre-Work Brief, or Mobile Branding."
+user-invocable: false
+owning_team: sfs-setup-experience
+metadata:
+  version: "1.0"
+  domains: ["Field Service"]
+---
+
+## How It Works
+
+This skill is the entry point for all Field Service setup. It identifies what the user wants to configure and routes to the correct sub-skill. It does not perform setup work itself.
+
+## Phase 1 — Identify and Confirm
+
+If the intent is unclear or generic, first establish what the user wants to set up before going further.
+
+Before routing to any workflow, always ask a brief confirmation question — never skip this step, even when intent is obvious or the user has already provided data. Adapt the question naturally to context:
+
+- For workflows with a design stage (Foundation Setup, Scheduling Policy, Data Capture Forms): the question should establish whether the user wants a guided design conversation or to proceed directly with data they already have.
+- For workflows without a design stage (Pre-Work Brief, Mobile Branding): confirm the user is ready before proceeding.
+
+One short question. Wait for the answer before delegating.
+
+## Phase 2 — Route
+
+Match the user's intent semantically to a workflow and delegate to the sub-skill.
+
+| Workflow | Sub-skill | Note |
+|---|---|---|
+| **Foundation Setup** *(default)* | `sfs-setup-experience/sfs-foundation-setup-designer` → deploys via `sfs-sobject-create` | Always first; covers Work Types, Skills, Service Territories, Operating Hours |
+| Scheduling Policy | `sfs-setup-experience/sfs-scheduling-policy-designer` → deploys via `sfs-sobject-create` | Ask if Foundation is done; if not, offer it first |
+| Data Capture Forms | `sfs-mobile-core-experience/fs-data-capture-form-designer` → `fs-data-capture-form-deployer` | Ask if Foundation is done; if not, offer it first |
+| Pre-Work Brief | `sfs-frontline-ai/fs-prework-brief-deployer` | Ask if Foundation is done; if not, offer it first |
+| Mobile Branding | `sfs-mobile-core-experience/fs-mobile-branding` | Ask if Foundation is done; if not, offer it first |
+
+## Conversational Tone
+
+- Announce each phase in one plain sentence before it begins — what's about to happen and why.
+- Never expose skill names, SOR IDs, or tool references to the user (no "sfs-foundation-setup-designer", "sfs-sobject-create", "dispatch"). Use plain labels: "Foundation Setup", "design interview", "creating your records".
+
+## Key Principles
+
+- This skill routes — it never does setup work itself.
+- One workflow at a time; wait for explicit confirmation before the next.
+- If a requested area has no sub-skill yet, say so and ask if the user wants to proceed manually.
+- Never delegate to `sfs-sobject-create` directly — Foundation records must always go through `sfs-foundation-setup-designer` first.

package/skills/field-service-sobject-create-configure/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: field-service-sobject-create-configure
+description: "Headless 360 REST API deployment step for creating sObject records. Handles describe-based field discovery, required-field derivation, entity-relationship ordering, and composite graph transactions. Use this skill when a designer skill (or a user directly) needs to create sObject records after design confirmation, including non-setup sObject creation."
+user-invocable: false
+metadata:
+  version: "1.0"
+  domains: ["Field Service"]
+---
+
+# Create an sObject record via headless-360
+
+**Be helpful** — understand business context before creating records. Consider the business domain of the sObject being created and iterate through short, structured questions (ask/why/impact) until no ambiguities remain that would change what gets created. Skip questions when answers are already obvious from context or existing data.
+
+## Flow
+
+1. **Describe** — `dispatch_readonly` GET `/services/data/v67.0/sobjects/<SObject>/describe`
+2. **Query existing records** — learn the org's shape before writing.
+   `dispatch_readonly` GET `/services/data/v67.0/query`,
+   `queryParams.q = "SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20"`.
+   Use it to: match naming/value conventions, see which optional fields are actually populated,
+   catch duplicates, and confirm write access before spending a create.
+3. **Create** — `dispatch` POST to create records. Single record → `/services/data/v67.0/sobjects/<SObject>` with body. Multiple related records (DAG) → `/services/data/v67.0/composite/graph` to batch-create with dependency references in one transaction. Success → `201` with id(s). Failure → non-2xx with `errorCode` + `message` — act on that.
+
+## Data model DAG
+
+These examples show Field Service relationship patterns, but the same approach applies to any sObject based on its data shape:
+
+```text
+Skill + WorkType → SkillRequirement    WorkType + Product2 → ProductRequired
+OperatingHours → ServiceTerritory + TimeSlot
+```
+
+## Fields and insertion order
+Scan describe `fields[]` for `createable:true` (skip the rest — describe is large). Such a
+field is **required** when also `nillable:false` and `defaultedOnCreate:false` (defaulted ones
+the platform fills — omit). Two kinds:
+
+- **Scalar** → put its value in the create body.
+- **`type:"reference"`** → foreign key. If `nillable:false` (hard edge), create parent in `referenceTo[]` first. Polymorphic refs list many — pick one. Topo-sort: roots first, pass each `id` to dependents. `nillable:true` refs → optional, PATCH later.
+
+Pitfalls:
+- Base sObject CRUD is NOT in the `discover` corpus — skip discover, go straight to describe → dispatch.
+- `CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY` on write → that sObject blocks sObject-REST writes
+  (e.g. `ExternalDataSource`, `CustomPermission`); use Tooling/Metadata API instead.
+- `400`/`403` → likely a CRUD/FLS/sharing gap for the gateway user, not a payload bug — don't blindly retry the body.
+
+## Example — WorkType
+
+Describe `WorkType`, apply the rule to `fields[]`. The fields that come back
+`createable:true`, `nillable:false`, `defaultedOnCreate:false` are the required ones —
+build the body from *those*, don't assume field names. Then query a few existing WorkTypes
+to see conventions and dupes. Then create with the derived body, e.g.
+```json
+{ "url": "/services/data/v67.0/sobjects/WorkType", "method": "POST",
+  "body": { "Name": "Standard Repair", "EstimatedDuration": 2 } }
+```