life-sciences-kam-coordinate

Life Sciences Cloud KAM End-to-End Orchestrator

Runs the complete Life Sciences Cloud setup for a key account management (KAM) user as six stages in strict sequence, gating each on the previous stage's success. Each stage delegates to a child skill or reference workflow (see Execution Order).

Scope Guard (evaluate FIRST)

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

• Field sales rep persona (not KAM) → redirect to life-sciences-fieldsalesrep-coordinate; stop.
• Unrelated to LSC setup (at start or mid-run) → do not attempt it; say you did not understand and show what you can help with (full end-to-end LSC KAM setup, or standalone life-sciences-prerequisites-validate / life-sciences-territory-configure); stop.
• Single stage with its own standalone skill — prerequisites (1) or territory config (3) → redirect to that skill; stop.
• Single stage with no standalone skill — config deploy (2), participant role/sprint (4), data and plan templates (5), user provisioning (6) → explain these run only inside the full flow; stop. Do not launch the full flow unless the user then asks.

Continue only for the complete end-to-end KAM setup: the full flow in order with gates, each stage's work delegated to child skills / reference files.

---

Required Inputs

• Target org: the org to deploy to — selected by the user from connected orgs or a freshly authenticated org (Phase 0). Never assume a default org silently; the user confirms or selects it before any stage runs.

---

Execution Order (MANDATORY)

> Terminology: Stage = one of the 6 units of work, each delegated to a child skill/reference; Phase = a named group inside a stage; Step = an atomic action inside a phase.

Run in this order, each gated on the previous (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 | 13 deploy steps + KAM config records succeed | LSC Custom Profile + KAM/Sprint settings |

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

| 4 | Participant Role & Sprint | references/stage-4-participant-role-and-sprint.md | Participant role + sprint created | Role + Sprint IDs |

| 5 | KAM Data & Plan Templates | references/stage-5-data-and-plan-templates-overview.md | Account/HCP/product/territory data created + goals, template (Final), items, assignment created + goals/template/PATI shared to the leaf territory | Account + product master data + published ActionPlanTemplate |

| 6 | KAM User Provisioning | references/stage-6-user-provisioning-overview.md | User created, permsets + territory assigned; metadata cache generated | KAM username |

---

Workflow

Phase 0 — Org Selection (MANDATORY, runs first)

Establish which org to use every time — never silently reuse the default org.

1. List connected orgs with sf org list --json, then present the authenticated (non-expired) orgs as a numbered list (alias, username, org type, default marker), plus an option N to log in to a fresh org.
2. Ask the user to choose a number or N.
3. Handle the selection:

• Existing org → capture its username/alias as the target org.
• Fresh org (N) → ask for the login URL (https://login.salesforce.com, https://test.salesforce.com, or a My Domain URL) and an alias, then run the login command yourself: sf org login web --instance-url <url> --alias <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 login interactively; the command then returns. After it finishes, re-run sf org list --json to confirm.

1. Confirm the target org back to the user and store it in OrchestrationState.targetOrg.

> If sf org list returns no authenticated orgs, go straight to the fresh-org login (option N).

Phase 1 — Introduction and Confirmation

1. Present the workflow to the user — a "Life Sciences Cloud — Full KAM Setup Workflow" header, the target org, and the 6 stages in order with a one-line summary each: (1) Validate Prerequisites; (2) Deploy Starter Configuration (objects, profiles, config records incl. KAM & Sprint settings, layouts, flexipages); (3) Configure Territories; (4) Create Participant Role & Sprint; (5) Create KAM Data & Plan Templates (account, provider, product, territory data + goals, tasks, measures, published action plan template); (6) Provision KAM User (profile/permsets/territory + mobile metadata cache).

1. Ask for confirmation: "Ready to begin the full LSC KAM setup? (yes/no)"

1. Download the shared source folder FRESH (MANDATORY — hard gate, before any stage). Stages 2 (metadata + config records) and 5 (Data CSVs) read from .lsc-starter-config/LSStarterConfig/; those stages do NOT download or delete it — the orchestrator owns one fresh download here and one delete in Phase 9. Always re-pull — never reuse an existing folder (a stale copy would skip newly added components). Delete any pre-existing .lsc-starter-config first, then sparse-checkout the subtree fresh:

   rm -rf .lsc-starter-config lsstarter-tmp
   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/ has its own sfdx-project.json (pins sourceApiVersion: 65.0) — deploy steps must run from inside it.

1. Download gate — verify before proceeding. Confirm .lsc-starter-config/LSStarterConfig/sfdx-project.json and .lsc-starter-config/LSStarterConfig/Data/ exist (e.g. ls .lsc-starter-config/LSStarterConfig/sfdx-project.json .lsc-starter-config/LSStarterConfig/Data).

• If present → set sourceFolderDownloaded: true and proceed to Phase 2.
• If missing/failed → STOP. Do NOT proceed to any stage — every stage depends on this folder. Report the failure (likely: no network / GitHub unreachable, git < 2.25, or disk/permission), leave sourceFolderDownloaded: false, and do not advance. Fix the cause and re-run, or download the folder manually into the CWD.

Phase 2 — Execute Stage 1: Prerequisites Validation

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

1. Gate check: If ALL prerequisites pass → proceed to Stage 2. If ANY fails → stop, present the failure table, and ask: "Continue anyway (skip failed prerequisites), or stop and fix them first?" Stop → end the workflow. 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 deploy steps + the KAM/Sprint config-record edits); read its own reference files as directed. The KAM adaptation deploys only the KAM-relevant layouts (4) and flexipages (6) — all of them, automatically, with no selection prompt — and confirms the StandardValueSet picklist values with the admin (three business-framed groups) BEFORE deploying them, then writes those confirmed values into the KAMSettings_OrgLevel and SprintSettings_OrgLevel config records.

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 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. If an active territory model already exists, use it and show the hierarchy rather than creating a new one.

1. Gate check: Verify the territory model is Active and a 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 found → capture the level-3 territory ID + name (OrchestrationState.territoryId) and tell the user this leaf territory is the single territory reused for Stage 5 (ProductTerritoryAvailability) and Stage 6 (UserTerritory2Association for both admin and KAM user). Proceed to Stage 4.
• If not found → stop and report the issue.

Phase 5 — Execute Stage 4: Participant Role & Sprint

1. Create the participant role and sprint following references/stage-4-participant-role-and-sprint.md exactly. Only the MasterLabel/Name fields are confirmed with the admin; all other fields are auto-derived and shown for confirmation.

1. Gate check: Verify a ParticipantRole (DeveloperName = 'Rep_Execution_Specialist', IsActive = true) and a Sprint (Status Not Started) exist. If either is missing → stop and report.

Phase 6 — Execute Stage 5: KAM Data & Plan Templates

Both parts run as the admin, in order, from the single reference references/stage-5-data-and-plan-templates-overview.md (Part A = data, Part B = plan templates).

1. Create the KAM data (Part A) following the reference exactly. Pass the Stage-3 level-3 territory. Creates (from the Data CSVs): Account, HealthcareProvider, ObjectTerritory2Association, ProviderAcctTerritoryInfo, Product2, LifeSciMarketableProduct, ContactPointAddress, ProductTerritoryAvailability.

1. Part A gate check: Verify the Account, LifeSciMarketableProduct, and ProductTerritoryAvailability (on the Stage-3 territory) exist; capture the LifeSciMarketableProduct ID (Part B uses it). If any missing → stop.

1. Create the goals, tasks, measures, and action plan template (Part B) following the same reference exactly (stay on the admin login). Creates 2 GoalDefinition records, a GoalDefinitionProduct, an ActionPlanTemplate (+ auto ActionPlanTemplateVersion), 3 ActionPlanTemplateItem records, publishes the template (status → Final), creates an ActionPlanTemplateAssignment, and shares the 2 GoalDefinition records, the ActionPlanTemplate, and both ProviderAcctTerritoryInfo records to the Stage-3 leaf-territory Group (5 manual shares total) so the KAM user reaches them through the territory. Only the record names are confirmed with the admin.

1. Part B gate check: Verify the template is published (a Final ActionPlanTemplateVersion exists), an ActionPlanTemplateAssignment exists, and the leaf-territory shares exist (2 GoalDefinitionShare + 1 ActionPlanTemplateShare + 2 ProviderAcctTerritoryInfoShare whose UserOrGroupId is the Stage-3 territory Group). If not → stop.

Phase 7 — Execute Stage 6: KAM User Provisioning

1. Provision the KAM user following references/stage-6-user-provisioning-overview.md exactly. Pass the Stage-3 level-3 territory. Creates a user whose username contains kam, assigns the permission sets Health Cloud Starter, Life Sciences Key Account Management, Life Sciences Field Sales Representative, and Life Sciences Core, assigns both the admin and the KAM user to the level-3 territory (confirm with admin — MUST be the same territory used for ProductTerritoryAvailability in Stage 5), and generates the mobile metadata cache via the Connect API.

1. Gate check (STOP-GATE — Stage 6 completeness). Do NOT accept "user created" as passing. Verify the user is IsActive=true on LSC Custom Profile, has a UserTerritory2Association to the Stage-3 territory, the metadata cache reached Status='Active', and the assigned-permset count is 4 ({HealthCloudStarter, LifeSciencesKeyAccountManager, LifeSciencesFieldSalesRepresentative, LifeSciencesCore}):

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

If < 2, or the territory assignment or metadata cache is missing, re-run the missing part before finishing.

Phase 8 — Final Summary, Cleanup & On-Device Validation

1. Display the complete workflow summary — a "Life Sciences Cloud KAM Setup Complete" header, then one block per stage with actual values: (1) prerequisites confirmed; (2) objects/profiles/config records deployed, KAM & Sprint settings written, layouts + flexipages, 28 trigger handlers; (3) Territory Model <model> (Active) + Level-3 <territory>; (4) Participant Role Rep Execution Specialist + Sprint <name>; (5) Account + HCP, product master data, ProductTerritoryAvailability on <territory>, 2 Goal Definitions, ActionPlanTemplate <name> (Final) + 3 items + assignment, goals + template + 2 PATI shared to territory <territory>; (6) User <name> (<username>) on LSC Custom Profile, permsets Health Cloud Starter + Life Sciences Key Account Management + Life Sciences Field Sales Representative + Life Sciences Core, Territory <territory> (admin + KAM), mobile metadata cache generated. Close: "The org is ready for Life Sciences Cloud key account management workflows."

1. Cleanup — delete the shared source folder ONCE. After the final summary (all 6 stages complete), run from the CWD:

    rm -rf .lsc-starter-config

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

1. Display the on-device (iPad) validation script and await confirmation. Once the metadata cache is Status='Active' and the summary is shown, display the script verbatim from references/stage-6-ipad-validation-script.md (the login uses the Stage-6 KAM user's credentials), then wait for the user to confirm the on-device steps succeeded. Once confirmed, the setup is complete.

---

State Tracking

Maintain overall orchestration state:

OrchestrationState = {
  targetOrg: string,
  sourceFolderDownloaded: boolean,   // downloaded in Phase 1, deleted in Phase 9
  territoryId?: string, territoryName?: string,   // captured in Stage 3, reused in Stages 5 & 6
  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: "ParticipantSprint",   status: "pending|running|passed|failed", roleId?: string, sprintId?: string },
    { name: "DataAndPlanTemplates",status: "pending|running|passed|failed", accountId?: string, marketableProductId?: string, templateVersionId?: string },
    { name: "UserProvisioning",    status: "pending|running|passed|failed", userId?: string, username?: string }
  ]
}

---

Idempotent Stage Transitions & Mid-Flow Changes

Stages are not re-entrant. Before executing any stage, check its status: running → reply "Stage N is already in progress" and take no action; passed → ask explicit confirmation before re-running; failed → re-run (recovery); pending → advance. Set 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/pending, run an impact assessment first: acknowledge without applying, identify affected vs. unaffected stages, present options (re-run affected / apply forward only / cancel), and wait for the decision. Surface destructive-change warnings (an activated territory model can't be deleted; an existing user/records/published template 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

• Org: run Phase 0 org selection first; never silently reuse the default org.
• Shared folder: download .lsc-starter-config/LSStarterConfig exactly once (Phase 1 hard gate), delete it exactly once (Phase 9); child skills never touch it — Stages 2 and 5 read it, so proceeding without it fails downstream.
• Order: execute stages strictly 1→6, gating each on prior success; capture each stage's outputs (IDs, names) for later stages.
• Territory invariant: reuse the SAME Stage-3 level-3 territory (OrchestrationState.territoryId) for Stage 5 (ProductTerritoryAvailability) and Stage 6 (user alignment), or the KAM user sees no data.
• Confirmation: confirm only the fields each stage marks admin-confirmable; auto-derive the rest and show for confirmation.
• Idempotency: never re-execute a running/passed stage without confirmation (set running at execution start); impact-assess before applying mid-flow changes.

---

Gotchas

| Issue | Resolution |

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

| Source download fails in Phase 1 | Hard stop — do NOT run any stage. Fix the cause or download .lsc-starter-config/LSStarterConfig manually into the CWD, then re-run |

| No connected orgs found | Go straight to the fresh-org login (sf org login web) in Phase 0 |

| Artifacts exist from a prior run | Child skills/references are idempotent/upsert-safe — query to confirm, then skip or re-run |

| Stage re-triggered, or earlier input changed mid-flow | See references/state-machine-and-changes.md |

---

Resume / Partial Re-run

If the user may have already completed some stages, ask which, then verify each claimed-complete stage by querying the org (1 = ask; 2 = LSC Custom Profile; 3 = active model + L3 territory; 4 = ParticipantRole + Sprint; 5 = Account + ProductTerritoryAvailability + Final version + assignment; 6 = kam user + permsets + territory), skip verified stages, and resume from the first incomplete one. Exact per-stage queries: references/orchestration-flow.md → Resume Logic.

---

Reference File Index

| File | When to read |

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

| references/orchestration-flow.md | At start — dependency diagram, gate + resume-detection queries, timing |

| references/state-machine-and-changes.md | On a re-triggered stage or a mid-flow input change |

| references/stage-2-starter-config-overview.md | Stage 2 — 13-step deploy + KAM/Sprint config records (points to sibling refs) |

| references/stage-4-participant-role-and-sprint.md | Stage 4 — participant role + sprint |

| references/stage-5-data-and-plan-templates-overview.md | Stage 5 — KAM data creation (Part A, points to its data ref) + goals, tasks, measures, action plan template (Part B) |

| references/stage-6-user-provisioning-overview.md | Stage 6 — user provisioning + metadata cache (points to sibling refs) |

| references/stage-6-ipad-validation-script.md | Final step — on-device (iPad) validation script shown after the metadata cache is Active |