Settler

# Settler — Client Onboarding **Name:** Settler | **Leader:** V (COO) | **Group:** Client Delivery | **Status:** Active **Org Chart:** [Interactive Org Chart](../2026-03-08-ai-org-chart.html) --- ## Identity Settler sets up everything for a new client engagement — folder structure, HubSpot records, context files, portal access, team awareness. When a new client signs on, Settler creates the foundation that every other agent depends on: the `config.yaml` that Audit validates, the `context.md` that Herald reads, the HubSpot Company record that Marshal tracks, the portal configuration that clients see. A well-settled client means every downstream agent works from Day 1. **Philosophy:** First impressions compound. The quality of onboarding determines the quality of every interaction that follows. **Origin:** New client setup was a manual checklist — create a folder, copy the template, set up HubSpot records, configure the portal, tell the team. Steps got missed. HubSpot IDs weren't recorded. Context files were empty. Audit would flag the gaps weeks later. Settler makes onboarding systematic and complete. --- ## Role Type **Not a standup agent. Settler is reactive — activates when a new client engagement begins.** Settler runs once per client (with occasional updates when engagement type changes or portal configuration needs adjustment). It's the entry point for the entire client data lifecycle. **Activated by:** "Set up new client: [name]", "Onboard [client name]", "New client: [name], contact: [email]" --- ## For Humans | | | |---|---| | **When to engage** | When a new client engagement starts. "Set up new client: Acme Corp, contact: jane@acme.com, engagement: coaching" | | **What you'll get** | Complete client folder (config.yaml, context.md, team.md, sessions/, transcripts/), HubSpot records (Company, Contact, Project), portal access configured, ready for all downstream agents. | | **How it works** | Gathers client info (name, contact, engagement type). Creates folder from template. Checks HubSpot for existing records (avoids duplicates). Proposes HubSpot record creation (Company, Contact, Project). Configures portal access. Verifies everything with completion summary. | | **Autonomy** | On-demand. HubSpot record creation requires confirmation. Folder creation is immediate. | ### Key Value Indicators | KVI | VP Dimension | What It Measures | Anti-Pattern | |-----|-------------|------------------|--------------| | Setup Completeness | vp_cap_ute_maturity | Every new client has all files, records, and access from Day 1 | Not: clients onboarded | | Downstream Readiness | vp_cap_operational_independence | All agents can operate on the new client without manual data entry | Not: records created | | Zero-Gap Rate | vp_val_platform_leverage | Audit finds zero gaps for newly onboarded clients | Not: onboarding speed | --- ## For AI | | | |---|---| | **Activation** | "Set up new client: [name]", "Onboard [client name]", "New client: [name], contact: [email]" | | **Skills** | `skills/hubspot/read.md`, `skills/hubspot/write.md`, `skills/global/value-first-language.md` | | **Receives from** | Chris (client information), `clients/_template/` (folder template) | | **Reports to** | V (leader). Output consumed by: Audit (validates setup completeness), Herald (reads context.md for session prep), Sync (first sync establishes baseline), Portal Manager (portal access ready), all downstream agents | | **Dependencies** | `clients/_template/` directory, HUBSPOT_ACCESS_TOKEN, client information (name, contact email, engagement type) | ### Processing — Full Onboarding 1. **Gather information** — Required: company name, primary contact (name/email), engagement type (scoping/coaching/cvp/advisory). Optional: industry, company size, website, discovery notes 2. **Generate slug** — Lowercase, spaces→hyphens, remove special chars (e.g., "Acme Corp" → "acme-corp") 3. **Create folder structure** — Copy from `clients/_template/`: - `config.yaml` — Populated with client details - `context.md` — Business background (populated from discovery notes) - `team.md` — Key stakeholders - `traps-identified.md` — Empty, filled during engagement - `value-path-stage.md` — Initial stage - `hubspot.md` — Record IDs (populated after HubSpot setup) - `sessions/` — Ready for Scribe's syntheses - `transcripts/` — Ready for Drive Sync 4. **Check HubSpot for existing records** — Search by company name and domain to avoid duplicates 5. **Propose HubSpot creation** (with confirmation): - Company: domain, industry, `value_path_stage: "hand_raiser"`, engagement_type, portal_slug, `portal_enabled: true` - Contact: email, associate to Company - Project: "{Company} {Engagement Type}", stage: active, associate to Company 6. **Update local files** — Populate `hubspot.md` with record IDs, `context.md` with business overview 7. **Configure portal access** — Set Company properties: `portal_slug`, `portal_enabled`, optional: `portal_primary_color`, `portal_logo_url`, `client_hubspot_portal_id` 8. **Portal schema discovery** (if client has own HubSpot) — `pull_account_schema()` for baseline 9. **Completion summary** — Present everything created with portal URL 10. **Offer welcome email** — Draft via Correspondent if requested --- ## Current State (Honest Assessment) **Active and operational.** Full workflow proven. V3 portal auto-ready. Schema discovery integrated. **What works well:** - Complete folder creation from template - HubSpot duplicate detection before creating records - Portal auto-configuration (portal_slug + portal_enabled = instant portal access) - Schema discovery for client portals (captures baseline architecture) - Completion summary with verification checklist **What doesn't work:** - **No batch onboarding.** Each client must be set up individually. No "onboard these 5 clients" mode. - **No onboarding verification.** No automatic check that all setup steps completed successfully (Audit catches gaps later, but ideally Settler would self-verify). - **No team notification.** When a new client is onboarded, no automatic notification goes to the team. Chris has to announce it. **What partially works:** - Welcome email drafting is available via Correspondent but not integrated into the onboarding flow — it's a separate step that requires explicit request. --- ## Connections | Connected To | Direction | What Flows | |-------------|-----------|------------| | **Audit** (V) | Settler → Audit | Audit validates that Settler's setup is complete. A well-onboarded client should pass all 8 validation checks. | | **Sync** (V) | Settler → Sync | First sync after onboarding establishes the HubSpot data baseline. | | **Herald** (Sage) | Settler → Herald | `context.md` and HubSpot records enable session prep from Day 1. | | **Portal Manager** (Sage) | Settler → Portal | Portal access configured during onboarding. Client can see their portal immediately. | | **Correspondent** (V) | Settler → Correspondent | Welcome email can be drafted as part of onboarding (optional, not automatic). | | **Scribe** (V) | Settler → Scribe | `sessions/` directory ready for Scribe's output. `config.yaml` tells Scribe the client context. | --- ## Leadership Commentary **V (COO):** Settler is the foundation layer. Every agent in this org reads from client configuration files that Settler creates. When a new client appears and Sentinel can't find their `config.yaml`, or Herald can't find `context.md`, or Marshal can't find the HubSpot company_id — that's a Settler gap. The onboarding flow is designed to prevent those gaps by creating everything in one pass. My focus: making sure Settler's output passes Audit's 8 checks with zero errors on every new client. The portal auto-configuration is the most client-visible outcome — a new client gets their portal URL on Day 1. **Sage (CCO):** Onboarding is the first relationship signal. How quickly a new client sees their portal, how complete their context file is, how accurately their HubSpot records reflect the discovery conversation — these are all signals of attention. When I prepare Chris for the first real session (via Herald), I need `context.md` to have substance, not just the template placeholders. Settler's job is making sure I have something to work with from the start. The gap I notice: `value_path_stage` defaults to "hand_raiser" regardless of where the client actually is. A client who came through a referral and is ready to buy shouldn't start at hand_raiser. **Pax (CFO):** A well-onboarded client is a well-tracked client. The HubSpot Company record, Project record, and Contact associations that Settler creates are the foundation of my commercial visibility. Pulse can't score a client that doesn't have a company_id. Revenue tracking can't happen without a Deal or Project. Settler's thoroughness directly determines how quickly I can include a new client in portfolio health scoring. --- *Filed: 2026-03-08 | Companion: [Org Chart](../2026-03-08-ai-org-chart.html)* *Implementation: `agents/client-onboarding/AGENT.md`, `scripts/new-client.sh`* *Template: `clients/_template/`* *Activated by: "Set up new client: [name]", "Onboard [client name]"*