life-sciences-fieldsalesrep-coordinate

Life Sciences Cloud End-to-End Orchestrator

Runs the complete Life Sciences Cloud setup workflow as five stages in strict sequence, gating each on the success of the previous stage. Each stage delegates to a child skill or a reference workflow, organized internally into phases and steps (defined under Execution Order below).

Scope Guard (evaluate FIRST)

Serve only requests for the full end-to-end LSC setup. A single stage/phase/step is never invokable here — never silently expand a partial ask into the whole flow. Before any work:

• Unrelated to LSC setup (at start or mid-run) → do not attempt it. Tell the user you did not understand the request and show what you can help with (full end-to-end LSC setup, or standalone life-sciences-prerequisites-validate / life-sciences-territory-configure); stop.
• Stage with its own standalone skill — prerequisites (Stage 1) or territory config (Stage 3) → redirect to life-sciences-prerequisites-validate / life-sciences-territory-configure; stop.
• Stage with no standalone skill — config deploy (2), user provisioning (4), visit creation (5) → explain these run only as part of the full flow, not on their own; stop. Do not launch the full flow unless the user then asks for it.

Continue only for the complete end-to-end setup: orchestrating the full flow (prerequisites → config deploy → territory → user provisioning → visit creation) in order with gates. Each stage's actual work is delegated to child skills / reference files.

---

Required Inputs

Gather before proceeding:

• Target org: The org to deploy to — selected by the user from the list of connected orgs, or a freshly authenticated org (see Phase 0). Never assume a default org silently; always have the user confirm or select the target org before any stage runs.

---

Execution Order (MANDATORY)

> Terminology: Stage = one of the 5 units of work (1–5), each delegated to a child skill or a reference workflow; Phase = a named group of work inside a stage; Step = an atomic action inside a phase. So "Stage 2 › Phase 1 › Step 3" reads top-to-bottom.

Run in this order, each gated on the previous (see the full dependency diagram in references/orchestration-flow.md):

| # | Stage | Runs | Gate (must pass to advance) | Output |

|---|-------|------|------------------------------|--------|

| — | Setup: download .lsc-starter-config/LSStarterConfig | — | Folder present (MANDATORY — hard stop) | Shared source folder in CWD |

| 1 | Prerequisites Validation | life-sciences-prerequisites-validate skill | All prerequisites PASS | Org confirmed ready |

| 2 | Starter Config Deploy | references/stage-2-starter-config-overview.md | All 13 deploy steps succeed | LSC Custom Profile exists |

| 3 | Territory Configuration | life-sciences-territory-configure skill | Territory model Active + L3 territory | Level-3 territory ID + name |

| 4 | User Provisioning | references/stage-4-user-provisioning-overview.md | User created, permsets + territory assigned | Rep username |

| 5 | Sample Visit Creation | references/stage-5-visit-creation-overview.md | Visit + supporting records created; metadata cache generated | — |

---

Workflow

Phase 0 — Org Selection (MANDATORY, runs first)

Before presenting the workflow, establish which org to use. Do this every time the user asks to set up Life Sciences Cloud — do not silently reuse the current default org.

1. List connected orgs:

   sf org list --json

Parse the result and present the authenticated orgs (non-expired) to the user as a numbered list — include alias, username, org type (Dev Hub / Sandbox / Scratch / Production), and the default marker if any:

   Connected Orgs — select the target for Life Sciences Cloud setup
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     1. ls-dev        alice@example.com          (Dev Hub)   [default]
     2. ls-sandbox    alice@example.com.sandbox  (Sandbox)
     3. partial-scr   test-xyz@example.com       (Scratch)

     N. Log in to a fresh org (opens a browser to authenticate a new org)

1. Ask the user to choose: "Which org would you like to use? Enter a number, or choose N to log in to a fresh org."

1. Handle the selection:

• Existing org chosen → capture its username/alias as the target org for all subsequent steps.
• Fresh org chosen (option N) → authenticate a new org interactively: ask for the login URL (My Domain / instance URL, e.g. https://mydomain.my.salesforce.com; https://login.salesforce.com for production, https://test.salesforce.com for a sandbox) and an alias (e.g. ls-setup), then run the login command yourself:

        sf org login web --instance-url <user-supplied-url> --alias <user-supplied-alias> --set-default

Do not hand the command to the user to run — execute it directly. It opens a browser on the user's machine for them to complete the web login interactively; the command then returns. After it finishes, re-run sf org list --json to confirm the new org, then use it as the target org.

1. Confirm the target org back to the user before proceeding: "Using <alias> (<username>) as the target org for Life Sciences Cloud setup." Store this in OrchestrationState.targetOrg.

> If sf org list returns no authenticated orgs, go straight to the fresh-org login flow (option N) — there is nothing to select from.

Phase 1 — Introduction and Confirmation

1. Present the workflow to the user:

   Life Sciences Cloud — Full Setup Workflow
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   This will execute 5 stages in sequence. Each stage is internally
   organized into phases and steps.

   Stage 1: Validate Prerequisites
            Checks org settings, permissions, and features

   Stage 2: Deploy Starter Configuration
            Deploys objects, profiles, config records, layouts, flexipages

   Stage 3: Configure Territories
            Creates territory type, model, and 3-level hierarchy

   Stage 4: Provision Field Sales Rep User
            Creates user, assigns profile/permsets, assigns to territory

   Stage 5: Create Sample Visit
            Logs in as the rep, creates account/provider/visit records,
            generates the mobile metadata cache

   Target org: <org>

1. Ask for confirmation: "Ready to begin the full Life Sciences Cloud setup? (yes/no)"

1. Download the shared source folder ONCE (MANDATORY — hard gate, before any stage). Both Stage 2 (Starter Config Deploy — metadata + config records) and Stage 5 (Sample Visit Creation — Data CSVs) read from .lsc-starter-config/LSStarterConfig/; those stages do NOT download or delete it — the orchestrator owns a single download here and a single delete in Phase 8. Sparse-checkout only that subtree (the repo is large) into the CWD:

   git clone --no-checkout --depth 1 --filter=blob:none \
     https://github.com/SalesforceLabs/LSStarterConfig.git lsstarter-tmp
   cd lsstarter-tmp && git sparse-checkout init --cone \
     && git sparse-checkout set Codey/LSStarterConfig && git checkout && cd ..
   mv lsstarter-tmp/Codey ./.lsc-starter-config && rm -rf lsstarter-tmp

> .lsc-starter-config/LSStarterConfig/ contains its own sfdx-project.json (pins sourceApiVersion: 65.0) — the deploy step (Phase 3) must run from inside it. If the folder already exists in the CWD (from a prior run), reuse it (skip the download).

1. Download gate — verify the folder exists before proceeding. Confirm the download succeeded by checking that .lsc-starter-config/LSStarterConfig/sfdx-project.json and .lsc-starter-config/LSStarterConfig/Data/ are present (e.g. ls .lsc-starter-config/LSStarterConfig/sfdx-project.json .lsc-starter-config/LSStarterConfig/Data).

• If present → set sourceFolderDownloaded: true in OrchestrationState and proceed to Phase 2.
• If the download failed or the folder/contents are missing → STOP. Do NOT proceed to any stage — every stage depends on this folder. Report the failure and stop:

     STOP: Setup cannot start — source download failed

     Could not download .lsc-starter-config/LSStarterConfig from
     https://github.com/SalesforceLabs/LSStarterConfig.git
     Likely: no network / GitHub unreachable, git < 2.25 (no sparse-checkout),
     or insufficient disk space / write permission in the CWD.

     Mandatory prerequisite — no stage can run without it. Fix the cause and
     re-run, or download the folder manually into the CWD, then re-run.

Leave sourceFolderDownloaded: false and do not advance the workflow.

Phase 2 — Execute Stage 1: Prerequisites Validation

1. Run the prerequisites validation following the life-sciences-prerequisites-validate skill workflow exactly.

1. Gate check: Review the results.

• If ALL prerequisites pass → proceed to Stage 2
• If ANY prerequisite fails → stop and present the failure report

   STOP: Stage 1 FAILED — Prerequisites not met
   
   <show the prerequisite failure table>
   
   Please resolve the failed prerequisites and re-run this workflow.

Ask the user: "Would you like to continue anyway (skip failed prerequisites), or stop and fix them first?"

• If user says stop → end the workflow
• If user says continue → proceed with a warning that later stages may fail

Phase 3 — Execute Stage 2: Starter Config Deploy

1. Run the starter config deployment following references/stage-2-starter-config-overview.md exactly (all 13 steps in order); read its own reference files as directed.

1. Gate check: Verify the LSC Custom Profile exists:

   sf data query --query "SELECT Id, Name FROM Profile WHERE Name = 'LSC Custom Profile'" --target-org <org> --json

• If profile exists → proceed to Stage 3
• If profile not found → stop and report deployment failure

Phase 4 — Execute Stage 3: Territory Configuration

1. Run the territory configuration following the life-sciences-territory-configure skill workflow exactly.

1. Gate check: Verify the territory model is Active and level-3 territory exists:

   sf data query --query "SELECT Id, Name, DeveloperName, Territory2Model.State FROM Territory2 WHERE ParentTerritory2.ParentTerritory2Id != null AND Territory2Model.State = 'Active'" --target-org <org> --json

• If level-3 territory found with Active model → capture the territory ID and name, proceed to Stage 4
• If not found → stop and report the issue

Phase 5 — Execute Stage 4: User Provisioning

1. Run the user provisioning following references/stage-4-user-provisioning-overview.md exactly; read its own reference file as directed. Pass the territory information captured from Stage 3.

1. Gate check: Verify the user exists, has the correct profile, all 4 permission sets, and territory assignment. Capture the rep username — Stage 5 logs in as this user.

> STOP-GATE (Stage 4 completeness). Do NOT accept "user created" as passing this gate — verify all four facets and STOP if any is short:

> ```bash

> sf data query --query "SELECT COUNT(Id) c FROM PermissionSetAssignment WHERE AssigneeId = '<newUserId>' AND PermissionSet.IsOwnedByProfile = false" --target-org <org> --json

> ```

> The permset count MUST be 4 ({LifeSciencesCore, LifeSciencesFieldSalesRepresentative, HealthCloudStarter, LifeSciencesKeyAccountManager}); the user MUST be IsActive=true on the LSC Custom Profile; and a UserTerritory2Association to the level-3 territory MUST exist. If the permset count is < 4 or any facet is missing, Stage 4 did not fully complete — re-run the missing part of references/stage-4-user-provisioning-overview.md (its own Phase 4/5 stop-gates cover this) before advancing to Stage 5. A rep missing a permset silently fails visit creation downstream with confusing permission errors.

Phase 6 — Execute Stage 5: Sample Visit Creation

1. Run the visit creation following references/stage-5-visit-creation-overview.md exactly; read its own reference files as directed. Pass the rep username captured from Stage 4. This stage:

• Logs in as the rep user (sf org login web) and creates account, healthcare provider, and visit records (rep-owned), plus territory associations and product master data (admin-owned).
• Generates the mobile metadata cache via the Connect API (admin-owned).

> This stage uses two identities — the rep user (from Stage 4) for visit records and the admin for product master data and metadata cache generation. Follow the child skill's rep/admin split exactly.

1. Gate check: Verify at least one Visit record was created:

    sf data query --query "SELECT Id, Name, AccountId FROM Visit ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json

• If a Visit exists → proceed to the final summary
• If no Visit found → stop and report the visit-creation failure

Phase 7 — Final Summary

1. Display the complete workflow summary — a "Life Sciences Cloud Setup Complete" header followed by one block per stage (substitute actual values from the run):

• Stage 1: all org prerequisites confirmed.
• Stage 2: objects/profiles/config records deployed, <N> layouts + <N> flexipages deployed, 28 trigger handlers activated.
• Stage 3: Territory Model <model name> (Active); Level-3 Territory <territory name>.
• Stage 4: User <firstName> <lastName> (<username>); Profile LSC Custom Profile; permission sets Life Sciences Core, Life Sciences Field Sales Representative, Health Cloud Starter, Life Sciences Key Account Management; Territory <territory name>; admin also assigned to the territory.
• Stage 5: Account + Healthcare Provider created; Visit <subject> (Territory <territory name>); product detailing/discussion records; mobile metadata cache generated (Connect API).

Close with: "The org is ready for Life Sciences Cloud field sales workflows."

Phase 8 — Cleanup (delete the shared source folder ONCE)

1. After the final summary (all 5 stages complete), delete the .lsc-starter-config folder downloaded in Phase 1 to leave the working directory clean. Run from the CWD (the parent of .lsc-starter-config/):

    rm -rf .lsc-starter-config

Do this silently — do NOT print a cleanup line or mention the folder deletion in the final output. Skip if the workflow stopped on a failure and the user may resume — keep the folder until the flow completes so a resumed stage can still read it. This is the single deletion for the whole flow; the child skills never delete it.

---

State Tracking

Maintain overall orchestration state:

OrchestrationState = {
  targetOrg: string,
  sourceFolderDownloaded: boolean,   // .lsc-starter-config/LSStarterConfig downloaded in Phase 1, deleted in Phase 8
  stages: [
    { name: "Prerequisites", status: "pending|running|passed|failed|skipped" },
    { name: "StarterConfig", status: "pending|running|passed|failed" },
    { name: "TerritorySetup", status: "pending|running|passed|failed", territoryId?: string, territoryName?: string },
    { name: "UserProvisioning", status: "pending|running|passed|failed", userId?: string, username?: string },
    { name: "VisitCreation", status: "pending|running|passed|failed", visitId?: string }
  ]
}

---

Idempotent Stage Transitions & Mid-Flow Changes

Stages are not re-entrant. Before executing any stage, check its status in OrchestrationState: running → reply "Stage N is already in progress" and take no action; passed → ask for explicit confirmation before re-running; failed → re-run (intentional recovery); pending → advance. Transition status to running at execution start (not on user input) so accidental double-confirms never run a stage twice.

If the user requests a change to an earlier stage's inputs while a later stage is in progress or pending, run an impact assessment first: acknowledge without applying, identify affected vs. unaffected stages, present options (re-run affected / apply going forward only / cancel), and wait for the decision. Surface destructive-change warnings (an activated territory model can't be deleted; an existing user/records remain).

The full behavior matrix, impact-assessment template, per-change impact mapping, and destructive-change warnings are in references/state-machine-and-changes.md.

---

Rules / Constraints

| Constraint | Rationale |

|-----------|-----------|

| Always run Phase 0 org selection first; list connected orgs and let the user pick or log in to a fresh org | User must explicitly choose the target org; never silently reuse the default |

| Download .lsc-starter-config/LSStarterConfig exactly once (Phase 1, MANDATORY hard gate) and delete it exactly once (Phase 8); child skills never download or delete it | Both child skills read from the shared folder — proceeding without it guarantees downstream failures |

| Execute stages strictly in order 1→5, gating each on prior success | Each stage depends on outputs from previous stages; prevents cascading failures |

| Never skip Stages 2 or 3, or Stage 4 before Stage 5 | User provisioning depends on profile + territory; visit creation logs in as the Stage-4 rep |

| Follow each child skill's workflow exactly; capture outputs (IDs, names) for later stages | Child skills have their own confirmations; avoids redundant re-queries |

| Never re-execute a running/passed stage without explicit confirmation; transition status to running at execution start, not on user input | Race-free idempotency against duplicate "Proceed" messages |

| Perform impact assessment before applying mid-flow changes | User must see what will break/redo before committing to a change |

---

Gotchas

| Issue | Resolution |

|-------|------------|

| Source download fails in Phase 1 (network/git/disk) | Hard stop — do NOT run any stage. Report the failure (see Phase 1 download gate); fix the cause or download .lsc-starter-config/LSStarterConfig manually into the CWD, then re-run |

| No connected orgs found | sf org list returns none — go straight to the fresh-org login (sf org login web) in Phase 0 |

| Fresh-org / rep login needs a browser | Run sf org login web yourself (Phase 0 org auth, Stage 5 rep login) — don't hand it to the user. It opens a browser on the user's machine; they complete the web login there and the command returns |

| Artifacts exist from a prior run (profile, territory, user, config) | The child skills are idempotent/upsert-safe and detect existing records — query the org to confirm, then skip or re-run safely |

| Visit creation uses two identities (rep + admin) | Product master data and metadata cache are admin-owned; follow the child skill's rep/admin split |

| Stage re-triggered, or user changes an earlier input mid-flow | See the transition matrix and impact assessment in references/state-machine-and-changes.md |

---

Resume / Partial Re-run

If the user may have already completed some stages (e.g. from a prior session), ask which, then verify each claimed-complete stage by querying the org (Stage 1 = ask; 2 = LSC Custom Profile; 3 = active model + L3 territory; 4 = user with correct profile/permsets; 5 = a Visit record). Skip verified stages and resume from the first incomplete one. Exact detection queries per stage are in references/orchestration-flow.md → Resume Logic.

---

Output Expectations

Deliverables:

• .lsc-starter-config/LSStarterConfig folder downloaded once (Phase 1) and removed once (Phase 8) — both done silently; not reported in the final summary
• All 5 stages executed successfully (or user-acknowledged skips)
• Full summary of what was created/configured
• Org ready for Life Sciences Cloud field sales workflows

---

Reference File Index

| File | When to read |

|------|-------------|

| references/orchestration-flow.md | At start — the dependency diagram, per-stage gate verification queries, resume-detection queries, and timing expectations |

| references/state-machine-and-changes.md | When a stage is re-triggered or the user changes an earlier input mid-flow — the full transition behavior matrix, impact-assessment template + mapping, and destructive-change warnings |

| references/stage-2-starter-config-overview.md | During Stage 2 (Phase 3) — the full 13-step starter-config deploy workflow; it points to its own sibling references as needed |

| references/stage-4-user-provisioning-overview.md | During Stage 4 (Phase 5) — the full field-sales-rep user provisioning workflow; it points to its own sibling reference as needed |

| references/stage-5-visit-creation-overview.md | During Stage 5 (Phase 6) — the full sample-visit creation workflow; it points to its own sibling references as needed |