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)
   

2. 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."

3. 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.

4. Confirm the target org back to the user before proceeding: "Using () 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>
   

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

3. 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).

4. 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

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

6. 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

7. 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.

8. 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

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

10. 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

11. 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.

12. 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:

    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

13. 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.

14. 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

15. 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 <name> (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)

16. 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