| name | crm |
| description | Find any client's status from HQ's canonical client record — the native ontology CRM. Use when asked "where is this client?", "what's the status of <company>?", "show the pipeline by stage", "what's happened with <client> lately?", or "do we have a record for <company>?". Reads the vault-synced CRM projection that already joins every GTM silo (inbound, pipeline, contract, billing) plus the activity timeline onto one account record. Company-agnostic; requires the company's crmEnabled setting. |
CRM — the canonical client record
HQ's native CRM makes the ontology the canonical client record. Every
account is one entity that already joins your GTM silos — inbound origin,
pipeline stage, contract, billing — with its activity timeline (meetings,
decisions, action items, commitments, risks) attached. This skill reads that
canonical record first, instead of hand-joining source systems at query
time.
Where the record lives
A per-company, vault-synced CRM projection (crm-projection.json) holds the
joined accounts. It is produced by the CRM engine in hq-pro and synced into the
company's vault, so the read is local and fast — no live calls to source systems.
Two ways to read it, in order of preference:
crm_* tools — the read-only programmatic surface over the projection,
when the CRM MCP surface is available for your host. Shape source of truth:
repos/private/hq-pro/src/ontology/crm/mcp-tools.ts.- The projection file directly — read the active company's synced
crm-projection.json from its vault. Each account carries external_ids, the
joined source legs, the funnel stage, and the timeline.
| Question | Read |
|---|
| "Do we have a record for <company>?" | accounts, by name/domain |
| "Where is this client?" / "status of <company>?" | the full joined account record |
| "Where is every client?" / "pipeline by stage" | accounts grouped by stage |
| "What's happened with <client> lately?" | the account's activity timeline |
A source leg shown as absent means missing source data, not a join failure.
Canonical record first
For any account-status / "where is this client?" / pipeline-shape question,
read the canonical record before touching any source system. The cross-silo
join is already done; reconstructing it by hand at query time is exactly the toil
this CRM removes.
Reach the source systems only for what the projection deliberately does not do:
- Brand-new inbound that may not be projected yet → the company's inbound
source of truth (e.g. its lead database).
- Writing stage changes, notes, or imported records → the company's CRM
system of record (the ontology is read-only inbound).
- Outreach — drafting/sending email, checking replies, booking state → the
company's mail/calendar connectors.
Which specific systems back a company (CRM of record, lead database, mail,
calendar, chat) and its stage vocabulary are company configuration, not part
of this skill. Read the company's own CRM knowledge/policies for those.
The join key
Accounts are joined across silos by an external_ids map on the entity
(external_ids.<provider> per source system). Each read-only adapter stamps its
provider's id on upsert; the resolver deduplicates by external id, then
normalized domain, then name. See the external-ids.md knowledge doc.
Enabling CRM for a company
CRM is gated per company by the crmEnabled company setting. When enabled,
the engine's adapters run and the projection is produced and synced. See the
enabling-crm.md knowledge doc. If a company has no projection yet, CRM is not
enabled (or has not synced) for it — say so rather than hand-joining sources as a
silent fallback.
Operating rules
- Canonical record first. Read the projection (or
crm_* tools) before any
source system for status / "where is it?" / pipeline questions.
- The projection is read-only inbound. Stage / notes / record mutations land
in the company's CRM system of record, not the ontology.
- Scope to one company. The projection is per-company and vault-scoped;
never read or join another company's CRM data.
- Don't leak secrets. Use
hq secrets exec --company <co> --only <KEY> -- <cmd>
for any source-system access; never print API keys or database URLs.
- Absent ≠ wrong. A missing source leg means missing source data; report it
as unknown rather than inferring.
- Stale or empty → say so. If the projection is missing or stale, report
that and offer to sync (
/hq-sync) rather than silently falling back to a
live hand-join.
Output
For status questions, answer from the joined record: the account's stage, its
source legs (absent legs called out), and the recent timeline with citations.
For audits or reconciliation, produce a compact report — what was checked, what's
missing or stale, and any ambiguous cases needing judgment.
