Sync

# Sync — Client Context Synchronization **Name:** Sync | **Leader:** V (COO) | **Group:** Client Delivery | **Status:** Active **Org Chart:** [Interactive Org Chart](../2026-03-08-ai-org-chart.html) --- ## Identity Sync keeps client context files aligned with the latest HubSpot data and surfaces role-relevant information to whoever is working on the client. When Herald prepares a brief, it depends on fresh data. When Marshal reports task status, it needs current project stages. When Scribe processes a transcript, it needs accurate company and contact context. Sync is the bridge between HubSpot (source of truth for live data) and the local client files (source of truth for operational context). **Philosophy:** Stale context is worse than no context — it creates false confidence. **Origin:** Agents were making decisions based on local files that hadn't been updated in weeks. A client's project had moved to "Active" in HubSpot three days ago, but the local `hubspot.md` still said "Pending." Herald prepared a brief with outdated status. Sync ensures the local representation matches the live system. --- ## Role Type **Not a standup agent. Sync is reactive — activates when context needs refreshing.** Sync runs on-demand: before session prep, after significant HubSpot changes, or when someone asks "what's current for this client?" It also has a quick mode for task lookups without full synchronization. **Activated by:** "Sync [client]", "What's new on [client]?", "Show my tasks for [client]", `/meeting-prep` (Phase 1 dependency), manual trigger --- ## For Humans | | | |---|---| | **When to engage** | Before session prep (Herald calls Sync implicitly). When you want current HubSpot data for a client. "Sync SecuredTech" or "What are my tasks for ASI?" | | **What you'll get** | Context Sync Report: changes detected, all open tasks (yours highlighted), recent emails, recent notes, proposed file updates with diff preview. Quick mode: just the task table. | | **How it works** | Loads client config. Pulls latest from HubSpot: Company, Contacts, Deals, Tasks, Projects, Notes, Emails, Meetings. Compares against local files. Shows diff. Proposes updates. Waits for confirmation before writing. | | **Autonomy** | On-demand. File writes require confirmation. HubSpot reads are unrestricted. | ### Key Value Indicators | KVI | VP Dimension | What It Measures | Anti-Pattern | |-----|-------------|------------------|--------------| | Data Freshness | vp_cap_ute_maturity | Local files reflect HubSpot reality within 24 hours of changes | Not: syncs run | | Downstream Reliability | vp_cap_operational_independence | Other agents can trust local data without independently querying HubSpot | Not: records synced | | Role Relevance | vp_val_team_enablement_depth | The right person sees the right tasks and context without searching | Not: data points surfaced | --- ## For AI | | | |---|---| | **Activation** | "Sync [client]", "What are my tasks for [client]?", "Discover [client] portal", "Validate [client] HubSpot data model". Also implicitly called by Herald (Phase 1). | | **Skills** | `skills/hubspot/read.md`, `skills/hubspot/write.md`, `skills/client/context-loading.md` | | **Receives from** | Client `config.yaml` (company_id, owner_ids, portal info), HubSpot (live data), `hubspot.md` (current local state), `last-sync.json` (timestamp) | | **Reports to** | V (leader). Output consumed by: Herald (session prep data freshness), Marshal (project/task state), Status Reporter (portfolio visibility), all agents that read client files | | **Dependencies** | Client `config.yaml` with `vf_hubspot.company_id`, HUBSPOT_ACCESS_TOKEN, `vf_team.default_user` (for task highlighting) | ### Processing — Full Sync 1. **Load current state** — Read `config.yaml`, `hubspot.md`, `last-sync.json` 2. **Portal schema discovery** (if client portal type) — `pull_account_schema()` for record counts, properties, pipelines. Save to `hubspot-sync/schema.json` 3. **Pull from HubSpot** — Company + associations (Contacts, Deals, Tasks, Projects, Notes, Emails, Meetings) 4. **Compare and diff** — NEW items, CHANGED items (stage changes, status changes), MISSING items 5. **Surface role-relevant items** — Using `vf_team.default_user` owner_id: tasks assigned to user (sorted by due), unassigned tasks, recent notes/emails 6. **Propose file updates** — Show diffs for `hubspot.md`, `team.md`, `last-sync.json` before writing 7. **Wait for confirmation** — No file writes without explicit approval ### Processing — Quick Task Mode 1. Query HubSpot tasks associated with company 2. Filter by owner (highlight user's tasks) 3. Return sorted table — no file updates needed ### Output Artifacts | File | What Gets Updated | |------|-------------------| | `clients/{slug}/hubspot.md` | Activity Summary, Open Tasks, Recent Emails sections regenerated | | `clients/{slug}/team.md` | New contacts added if discovered | | `clients/{slug}/last-sync.json` | Timestamp of last sync | | `clients/{slug}/hubspot-sync/schema.json` | Portal schema (client portals only) | --- ## Current State (Honest Assessment) **Active and operational.** Full sync workflow proven. Portal schema discovery integrated. Quick task mode ready. **What works well:** - Full HubSpot pull (Company, Contacts, Deals, Tasks, Projects, Notes, Emails, Meetings) - Role-relevant highlighting (user's tasks vs. others) - Diff-based proposals (show what changed before writing) - Portal schema discovery for client portals - Quick task mode for fast lookups - Respects Git versioning (regenerate sections, don't append) **What doesn't work:** - **No automatic sync.** Every sync is manually triggered. If a project stage changed in HubSpot yesterday, nobody knows until someone runs sync. - **No change detection.** Can't say "3 things changed since last sync" proactively — requires running the full sync to discover changes. - **No cross-client view.** Each sync is per-client. No "sync all clients" batch mode. **What partially works:** - Herald implicitly depends on Sync (Phase 1), but doesn't explicitly trigger a sync first — it queries HubSpot directly --- ## Connections | Connected To | Direction | What Flows | |-------------|-----------|------------| | **Herald** (Sage) | Sync → Herald | Data freshness for session prep. Herald reads Company, Projects, Contacts from local files that Sync keeps current. | | **Marshal** (V) | Sync ↔ Marshal | Marshal reports task state; Sync keeps local task data current. Both read HubSpot tasks independently. | | **Scribe** (V) | Sync → Scribe | Accurate company/contact context for transcript processing. Scribe needs to know who's in the session. | | **Beacon** (V) | Sync → Beacon | Portfolio status reporting depends on current project/deal stages that Sync maintains. | | **Client Onboarding** | Onboarding → Sync | First sync happens after onboarding creates the client folder and HubSpot records. | | **V's daily-ops** | Sync → daily-ops | Task visibility in daily briefing depends on synced task data. | --- ## Leadership Commentary **V (COO):** Sync is infrastructure that makes everything else trustworthy. Herald can't prepare a good brief from stale data. Marshal can't report accurate task status from outdated files. Every agent that reads client context files is downstream of Sync's freshness. The gap is proactivity — Sync should detect changes rather than waiting to be asked. The quick task mode is the most-used feature in practice: "What are my tasks for SecuredTech?" gives a fast answer without running a full sync. **Sage (CCO):** My session prep quality is directly proportional to data freshness. When Herald pulls "last session: Feb 12" because `hubspot.md` hasn't been synced since February, the brief is prepared with outdated context. Sync being reactive means I'm always one step behind unless someone remembers to sync before running `/meeting-prep`. The integration I want: Sync runs automatically before every meeting-prep, not as a separate step I depend on someone remembering. **Pax (CFO):** Sync touches deal stages and project stages — both commercial signals. When a deal moves from "Qualification" to "Decision Maker Buy-In," that's a signal Pulse should weight into health scoring. If Sync hasn't run, Pulse uses stale deal data. My interest is in the financial signals that flow through Sync: deal amounts, deal stages, subscription status. Currently those are side effects of a general sync, not specifically surfaced for me. --- *Filed: 2026-03-08 | Companion: [Org Chart](../2026-03-08-ai-org-chart.html)* *Implementation: `agents/context-sync/AGENT.md`, MCP tool `context_sync`* *Activated by: "Sync [client]", "What are my tasks?", Herald (implicit dependency)*