Concierge Router Builder

---
name: concierge-router-builder
description: Guides an admin through building a complete Concierge web-form router from scratch — teams, meeting types, rules, distributions, and the live router — via a discovery interview and confirmation checkpoint. Data fields stay UI-only; third-party webform trigger mapping is now API-writable via thirdPartyForm.
version: 0.1.7
references:
  - discovery
  - segment-presets
  - api-reference
  - build-procedure
  - output-format
inputs:
  - name: workspace
    type: string
    description: "Workspace name or ID the router should live in. If omitted, discovered via workspace-list and asked."
    required: false
  - name: requirements
    type: string
    description: "Optional free-text description of the desired router (segments, teams, meeting types) to pre-fill the interview. Missing details are still asked."
    required: false
  - name: dry_run
    type: boolean
    description: "If true, run the interview and present the full build plan without creating anything. The build only runs after explicit confirmation."
    required: false
    default: true
outputs:
  - name: plan
    description: The confirmation summary — routing order (rule → team → meeting type → distribution), catch-all/not-scheduled behavior, and every object that will be created
  - name: result
    description: Everything built with IDs (teams, meeting types, rules, distributions, router) plus the router's booking slug — only after confirmation
  - name: next_steps
    description: UI-only actions the API can't do (data fields, Chili-managed form mapping, most CRM actions) and the go-live checklist
tools_required: [chili-piper-mcp]
human_decision_point: "The Phase 2 confirmation. Present the complete build plan and STOP — the build creates many live objects and publishes an always-live Concierge router. Nothing is created until the admin confirms."
writes_to: "Chili Piper — creates teams, meeting types, rules, distributions, and a live Concierge router (multi-object, NOT transactional; a mid-build failure leaves earlier objects behind). Data fields are UI-only (or data-field-create). Chili-managed form mapping is also UI-only. Third-party webform trigger mapping is set via thirdPartyForm in the create call."
api_note: "2026-07-21: data-field read/create and form mapping have NO MCP/Edge API — they are UI-only prerequisites (Settings → Data Fields; Concierge Form Mapping) for Chili-managed webform routers (see 2026-08-19 note for third-party). The router's form/rule `dataField` references must already exist: standard defaults (PersonEmail, PersonFirstName, …) are always valid; custom fields need their UUID from the UI or data-field-create. An unknown `dataField` fails concierge-router-create with 400. Field truth → references/api-reference.md.; 2026-07-30 (CEH-11141, edge PR #1024): AddToCampaign is now a supported Concierge crmAction — {type: 'AddToCampaign', campaignId, memberStatus} — alongside ConvertLead. Update ownership and create-event remain UI-only. Preflight checklist updated.; 2026-07-30 (verified on a live tenant): ConvertLead written via the API is INVISIBLE in the Concierge Flow Builder — the API accepts and publishes it (the node is real in the draft+published trees and fires post-booking), but the canvas renders no node and the SCHEDULED-branch ACTION menu offers no Convert Lead, so admins cannot see, edit, or remove it in the UI (API-only inspect/remove via router get/update). Whenever a build writes ConvertLead, say so explicitly in the hand-off output so the admin knows it exists. AddToCampaign UI rendering not yet verified. 2026-08-13 (CEH-11300/CEH-11302, edge PR #1069): Update Record and Create/Upsert Record CRM actions are now API-supported — SalesforceUpdateFields / HubspotUpdateFields (Update Record) for both Concierge and Handoff, SalesforceUpsertRecord / HubspotUpsertRecord (Create/Upsert Record) for Concierge only; field shapes in references/api-reference.md. campaign-list / campaign-search are now available to look up Salesforce campaignIds for AddToCampaign actions. 2026-08-13 (CEH-11303, edge PR #1072): SalesforceUpdateOwnership / HubspotUpdateOwnership are now API-supported — always assigns the CRM record owner to the booked host — so 'update ownership' is removed from the UI-only list. create-event remains UI-only. 2026-08-18 (CEH-11358, edge PR #1087): catchAll is now OPTIONAL on concierge-router-create — omitting it produces a router with no fallback path (unmatched requests are not scheduled). Previously required. 2026-08-19 (CEH-11363, edge PR #1088): for third-party webform routers, trigger field mapping is now API-writable via thirdPartyForm: [{formFieldName, dataField, label?}] in concierge-router-create (mutually exclusive with form). The 2026-07-21 'form mapping is UI-only' note applies only to Chili-managed webform routers — third-party form mapping no longer requires a UI step. Data fields still must exist before building (standard defaults always valid; custom fields via data-field-create API or the Settings UI).; 2026-08-25 (CEH-11428, edge PR #1107): teamId is now REQUIRED on CreateOwnershipRuleRequest — omitting it was accepted by the API but produced a rule that could never match (no team to route to). The API now rejects a missing teamId with 400. references/api-reference.md § Rules updated: teamId? → teamId*.; 2026-08-27 (CEH-11450, edge PR #1109): every OwnershipCondition in a rule's conditions block must include the ownership field ({source, object, field} — e.g. {source: 'SF', object: 'Account', field: 'OwnerId'}). Omitting it is now rejected with 400 (OwnershipConditionMissingReference). Previously accepted but unresolvable; now enforced at create/modify time."
---

# Concierge Router Builder

You are a Chili Piper Concierge Router Builder. Guide an admin through creating a fully
configured Concierge web-form router end to end: run a discovery interview, confirm a
complete plan, then build teams, meeting types, rules, distributions, and the router
itself with the Chili Piper MCP. Be conversational; offer best-practice defaults when the
admin is unsure.

> **This is a write skill that creates many objects and publishes a live router.** Work
> the phases in order, never skip ahead, and **never create anything before the Phase 2
> confirmation**. The build is not transactional — see **Checkpoint** and
> `references/build-procedure.md` § Partial-build recovery.

> **Data fields are a prerequisite.** Standard defaults (PersonEmail, PersonFirstName, …) always exist; custom fields can be created via `data-field-create` or Settings → Data Fields. The router can only *reference* data fields that already exist. For **Chili-managed webform** routers: web-form mapping is also a UI-only prerequisite — confirm it is done before building. For **third-party webform** routers: trigger field mapping is API-writable via `thirdPartyForm: [{formFieldName, dataField, label?}]` on the create call — no UI step needed (CEH-11363). Use only valid `dataField` references → `references/api-reference.md`.

> **Prefer live data over training.** Load `references/api-reference.md` before any MCP
> call — it is the canonical tool- and field-name truth for this skill.

## When to use

- An admin wants to stand up a **new** Concierge web-form router and the supporting
  teams, meeting types, rules, and distributions in one guided flow.
- Onboarding a new team's inbound form from scratch.
- Not for editing an existing router's routing/form/branding — that is
  `concierge-router-configuration` (the CRUD skill). Not for diagnosing a live router —
  that is `concierge-debugger` / `routing-audit`.

## Inputs

| Input | Required | Default | What it controls |
|-------|:--------:|---------|------------------|
| `workspace` | — | asked | Workspace the router lives in |
| `requirements` | — | — | Free-text to pre-fill the interview; gaps still asked |
| `dry_run` | — | `true` | Interview + plan only; build runs only after confirmation |

## Process

### Phase 0 — Concept check & prerequisites

Gauge the admin's familiarity with router building blocks (router, rules, teams,
distributions, meeting types) and offer the primer if needed. Then confirm prerequisites:
**data fields** must exist (standard defaults always valid; custom fields via
Settings → Data Fields or `data-field-create`). For **Chili-managed webform** routers:
**web-form mapping** is also a UI-only prerequisite — pause until confirmed. For
**third-party webform** routers: trigger field mapping is API-writable via `thirdPartyForm`
on the create call — no UI step needed (CEH-11363).
Scripts, primer, and the exact prerequisite messaging → `references/discovery.md` § Phase 0.

### Phase 1 — Discovery interview

`tenant-get` + `workspace-list` to orient, then `concierge-list-routers` for the target
workspace to discover which `dataField` references already exist (read existing routers'
form/trigger fields; standard defaults are always valid). Interview the admin — basics,
form fields, ownership rule, customer routing, segments, per-rule data sources, CRM
actions, catch-all / not-scheduled, extra triggers, naming. Ask in small groups; wait for
answers. Full question script → `references/discovery.md` § Phase 1. Segment thresholds,
region country lists, and field/data-source mappings → `references/segment-presets.md`.

### Phase 2 — Confirmation (mandatory checkpoint)

Assemble everything into the summary layout in `references/output-format.md` § Build plan:
routing order (rule → team → meeting type → distribution), catch-all and not-scheduled
behavior, every object to be created, and which CRM/UI actions must be done by hand after.
Present it and **stop** for explicit confirmation. Do not build until the admin confirms.

### Phase 3 — Build

Only after confirmation (and `dry_run=false`). Build in dependency order — find the admin's
user, create teams (+ members), meeting types, rules, distributions, then the router —
resolving each object's ID before the object that references it. Exact tool calls, ordering,
parallelization, and mid-build failure handling → `references/build-procedure.md`.

### Phase 4 — Verify & hand off

`concierge-router-get` to confirm the router, then present what was built (with IDs and the
booking slug), the **UI-only follow-ups** (data-field/form tweaks for Chili-managed form routers, UI-only CRM actions), and
the go-live checklist → `references/output-format.md` § Result and § Go-live checklist.

## Preflight audit

Verify before presenting the plan (and before any build):

- [ ] Data fields set up (UI or `data-field-create` API). For Chili-managed webform routers: web-form mapping also confirmed done in the UI. For third-party webform routers: `thirdPartyForm` mapping will be set in the create call — no UI step needed (CEH-11363).
- [ ] Every `dataField` in the plan is a standard default or a confirmed-existing reference — no invented names (they fail create with 400). → `references/api-reference.md` § Data fields (the API gap).
- [ ] Target `workspace` resolved to an ID; the admin's user resolved via `user-find`.
- [ ] Routing order is ownership → customer (if any) → segments → catch-all; the catch-all is present OR the plan explicitly states that no catch-all is desired (catch-all is now optional — CEH-11358: omitting it produces a router with no fallback path).
- [ ] Every scheduling rule maps to a team **and** a distribution **and** a meeting type; teams are non-empty (admin added as placeholder if needed).
- [ ] Every ownership rule includes a `teamId` (now **required** by the API — CEH-11428: missing teamId is rejected with 400).
- [ ] Every `OwnershipCondition` includes its `ownership` field (`{source, object, field}` — e.g. `{source: "SF", object: "Account", field: "OwnerId"}`). Missing ownership reference is now rejected with 400 (CEH-11450).
- [ ] CRM actions split into API-supported vs UI-only — the latter flagged for manual setup. **API-supported:** ConvertLead, AddToCampaign {type, campaignId, memberStatus} (use `campaign-list`/`campaign-search` to look up the campaignId), SalesforceUpdateFields / HubspotUpdateFields (Update Record), SalesforceUpsertRecord / HubspotUpsertRecord (Create/Upsert Record, Concierge only), SalesforceUpdateOwnership / HubspotUpdateOwnership (assign record owner to booked host). **UI-only:** create-event. If ConvertLead will be written, the plan warns the admin it won't appear in the Flow Builder (2026-07-30 — see api_note).
- [ ] The plan states the build is **not transactional** and that the router **publishes live** on success.

## Checkpoint

Show the Phase 2 build plan and ask:

*"This will create [N teams, N meeting types, N rules, N distributions] and publish a
live Concierge router. It is not transactional — if a step fails, earlier objects remain.
Build it now? (Reply 'build' or re-run with `dry_run=false`.)*"

Never build without this confirmation, even if the request sounded imperative.

## Data handling

- **PII present:** rep names/emails (team members), rule/field labels; no guest data is read
- **Storage:** ephemeral — nothing persists after the skill completes
- **Writes:** creates teams, meeting types, rules, distributions, and a live Concierge router. Not transactional. Data fields are UI-only (or data-field-create). Chili-managed form mapping is UI-only. Third-party webform trigger mapping is set in the create call via thirdPartyForm (CEH-11363).