Design Crm

---
type: Skill
name: design-crm
description: Manage the NV oOS Pro Toolkit CRM — leads, deals, companies, contacts, customers, activities, and support tickets. Covers the complete sales pipeline from lead capture through qualification, deal management, and post-conversion customer tracking with BANT/MEDDIC scoring, activity logging, and workflow automation. Use when working with CRM records, managing pipeline stages, qualifying leads, creating company profiles, logging calls/emails/meetings, or troubleshooting CRM data issues.
license: Proprietary. See LICENSE.txt
metadata:
  type: Skill
---

# NV oOS Pro Toolkit CRM

The Pro Toolkit CRM is a complete sales and customer relationship management
system built on WordPress Custom Post Types. It manages the full lifecycle:
**lead capture → qualification → deal management → conversion → customer retention**.
All entities are stored as CPT records accessible via the `toolkit_cpt` MCP tool.

## WP-CLI Commands

Key `mcp-ai` WP-CLI commands for CRM operations. Run via `terminal`:

| Command | Use for |
|---|---|
| `wp mcp-ai cron` | Check CRM automation cron events (lead scoring, workflow triggers) |
| `wp mcp-ai queue` | Inspect CRM background jobs, retry failed imports |
| `wp mcp-ai bulk` | Bulk import/export CRM records |
| `wp mcp-ai health` | Verify CRM system health before running automations |
| `wp mcp-ai log` | View CRM workflow execution logs |

## When to use this skill

Trigger when ANY of the following is true:

- Viewing, searching, or filtering leads, deals, companies, customers, or activities.
- Creating or updating CRM records (leads, deals, companies, contacts, customers, activities, tickets).
- Qualifying leads using BANT or MEDDIC frameworks.
- Moving a deal through pipeline stages (inquiry → scoping → qualification → proposal → negotiation → engagement_signed).
- Converting a lead to a deal, or a deal to a customer.
- Logging sales activities: calls, emails, meetings, tasks, notes with dispositions.
- Building company profiles with industry, size, website, and status metadata.
- Managing support tickets with SLA tracking.
- Bulk importing leads or companies from CSV/email sources.
- Triaging the CRM pipeline — identifying hot leads, stalled deals, overdue follow-ups.
- Setting up CRM workflow rules for lead scoring, auto-assignment, or stage progression.
- Searching CRM records by email, company, status, or BANT score.

## Mental model — CRM entities and lifecycle

The CRM is organized around six core entity types connected by a lifecycle:

```
LEAD ──(qualified)──→ DEAL ──(won)──→ CUSTOMER
  │                     │                 │
  ├── activities        ├── activities    ├── activities
  ├── company           ├── company       ├── company
  └── contacts          └── contacts      └── contacts

TICKET ─── support requests, independent of lifecycle but linked to contacts/companies
```

**Relationships:**
- A **Lead** can be linked to a **Company** and **Contacts** (via `_company_id`, `_contact_id` meta).
- A **Deal** is linked to its source **Lead** via `lead_id` meta.
- A **Customer** is the post-conversion record after a deal is won.
- **Activities** link to any entity via `related_type` + `related_id` (e.g., `related_type: "lead"`, `related_id: 12398`).
- **Tickets** are independent support records that may reference a customer or company.

## CRM Entity Types

All CRM entities are managed through the **`toolkit_cpt`** MCP tool. Use the appropriate
`post_type` slug for each entity:

| CPT Slug | Label | Purpose | Key Meta Fields |
|---|---|---|---|
| `mcp_ai_lead` | Leads | Inbound lead capture, scored and staged | `first_name`, `last_name`, `email`, `phone`, `source`, `lead_status`, `lifecycle_stage`, `lead_score`, `bant_assessment` |
| `mcp_ai_deal` | Deals | Pipeline opportunities with stage tracking | `lead_id`, `deal_name`, `amount`, `currency`, `pipeline_stage`, `expected_close_date`, `deal_owner`, `win_probability` |
| `mcp_ai_company` | Companies | Organization profiles | `_company_industry`, `_company_size`, `_company_website`, `_company_phone`, `_company_address`, `_company_status`, `_company_assigned_to` |
| `mcp_crm_contacts` | Contacts | Individual contact records | Custom meta (varies by implementation) |
| `mcp_ai_customer` | Customers | Post-conversion customer records | Custom meta (varies by implementation) |
| `mcp_ai_crm_activity` | Activities | Calls, emails, meetings, tasks, notes | `activity_type`, `related_type`, `related_id`, `due_date` |
| `mcp_ai_ticket` | Support Tickets | ITIL-aligned SLA-tracked tickets | Custom meta (varies by implementation) |
| `mcp_ai_sequence` | Sequences | Automated outreach sequences | Custom meta |
| `mcp_crm_campaigns` | Campaigns | Marketing campaign records | Custom meta |
| `mcp_ai_crm_wf_rule` | Workflow Rules | Automation rules for CRM | Custom meta |

### Lead Meta Fields (detailed)

| Field | Type | Description | Example |
|---|---|---|---|
| `first_name` | string | Lead's first name | `"Scher"` |
| `last_name` | string | Lead's last name | `"Jill"` |
| `email` | string | Contact email address | `"jill.scher@cbiz.com"` |
| `phone` | string | Contact phone number | `""` |
| `source` | string | Lead source channel | `"email"`, `"webform"`, `"referral"`, `"upwork"` |
| `lead_status` | string | Current lead status | `"new"`, `"contacted"`, `"qualified"`, `"disqualified"` |
| `lifecycle_stage` | string | Lifecycle stage | `"lead"`, `"mql"`, `"sql"`, `"opportunity"` |
| `lead_score` | string | Numeric lead score (0-100) | `"62"` |
| `bant_assessment` | object | BANT qualification scores | See BANT/MEDDIC section below |
| `_source_message_id` | string | Source email message ID | `"19fd8cceb7c8e589"` |

### Deal Meta Fields (detailed)

| Field | Type | Description | Example |
|---|---|---|---|
| `lead_id` | string | Source lead post ID | `"12324"` |
| `deal_name` | string | Descriptive deal name | `"NUGL Media - Growth Capital"` |
| `amount` | string | Deal amount (string for precision) | `"0"`, `"50000"` |
| `currency` | string | ISO currency code | `"USD"` |
| `pipeline_stage` | string | Current pipeline stage | `"qualification"` |
| `expected_close_date` | string | Expected close date | `""`, `"2026-09-15"` |
| `deal_owner` | string | WordPress user ID of owner | `"1"` |
| `win_probability` | string | Win probability (0-1) | `"0.1"`, `"0.75"` |

**Pipeline stages (standard flow):**
```
inquiry → scoping → qualification → proposal → negotiation → engagement_signed
                                                                  └──→ won/lost
```

### Activity Meta Fields (detailed)

| Field | Type | Description | Example |
|---|---|---|---|
| `activity_type` | string | Type of activity | `"task"`, `"call"`, `"email"`, `"meeting"`, `"note"` |
| `related_type` | string | Entity type this activity belongs to | `"lead"`, `"deal"`, `"company"`, `"customer"` |
| `related_id` | string | Post ID of the related entity | `"12398"` |
| `due_date` | string | Due date for tasks | `"2026-08-08"` |

### Company Meta Fields (detailed)

| Field | Type | Description | Example / Enum |
|---|---|---|---|
| `_company_industry` | string | Industry vertical | `"Technology"`, `"Healthcare"`, `"Finance"` |
| `_company_size` | string | Size tier | `"1-10"`, `"11-50"`, `"51-200"`, `"201-1000"`, `"1000+"` |
| `_company_website` | string | Company website URL | `"https://example.com"` |
| `_company_phone` | string | Primary phone | `"+1-555-0100"` |
| `_company_address` | string | Headquarters address | `"123 Main St, Suite 100"` |
| `_company_status` | string | CRM pipeline status | `"prospect"`, `"lead"`, `"qualified"`, `"customer"`, `"churned"` |
| `_company_assigned_to` | int | WordPress user ID of owner | `1` |

## BANT / MEDDIC Scoring

Leads are automatically scored using **BANT** (Budget, Authority, Need, Timeline) with
four sub-scores, each 0-100. The `bant_assessment` object has this structure:

```json
{
  "budget": {
    "score": 50,
    "evidence": "invest; $; "
  },
  "authority": {
    "score": 50,
    "evidence": "cto; director; "
  },
  "need": {
    "score": 100,
    "evidence": "need; problem; challenge; solution; "
  },
  "timeline": {
    "score": 75,
    "evidence": "urgent; by; immediately; "
  }
}
```

**Total BANT score** = sum of all four sub-scores (max 400).

For **enterprise deals**, supplement BANT with MEDDIC:
- **M**etrics: Quantifiable value the solution delivers.
- **E**conomic Buyer: Who controls the budget?
- **D**ecision Criteria: What are the formal evaluation criteria?
- **D**ecision Process: What's the purchasing process?
- **I**dentified Pain: What problem are they solving?
- **C**hampion: Who is your internal advocate?

Use `bant_assessment` for automated lead scoring. For enterprise deals, manually track
MEDDIC elements in the deal `content` field or as additional meta.

## Available Tools

All CRM operations use the **`toolkit_cpt`** MCP tool. This is the single interface
for all CRM CRUD operations.

### Discovery

```
# List all available CRM post types
toolkit_cpt(action: "list_types")

# Get field schema for any CRM type
toolkit_cpt(action: "get_schema", post_type: "mcp_ai_lead")
```

### Reading records

```json
// List leads (most recent first):
{ "action": "list_items", "post_type": "mcp_ai_lead", "orderby": "date", "order": "DESC", "per_page": 20 }

// Search leads by email:
{ "action": "list_items", "post_type": "mcp_ai_lead", "search": "jill.scher@cbiz.com" }

// Filter by meta field:
{ "action": "list_items", "post_type": "mcp_ai_lead", "filters": [{ "key": "lead_status", "value": "new" }] }

// Get a single record:
{ "action": "get_item", "post_type": "mcp_ai_lead", "item_id": 12398 }
```

### Creating records

```json
// Create a lead with BANT scoring:
{ "action": "create_item", "post_type": "mcp_ai_lead", "fields": {
  "title": "Jane Smith", "first_name": "Jane", "last_name": "Smith",
  "email": "jane@acmecorp.com", "phone": "+1-555-0100", "source": "referral",
  "lead_status": "new", "lifecycle_stage": "lead", "lead_score": "50",
  "bant_assessment": {
    "budget": { "score": 0, "evidence": "" },
    "authority": { "score": 25, "evidence": "manager;" },
    "need": { "score": 50, "evidence": "looking for;" },
    "timeline": { "score": 25, "evidence": "soon;" }
  }
} }

// Create a company:
{ "action": "create_item", "post_type": "mcp_ai_company", "fields": {
  "title": "Acme Corporation", "_company_industry": "Manufacturing",
  "_company_size": "201-1000", "_company_website": "https://acmecorp.com",
  "_company_phone": "+1-555-0200", "_company_status": "prospect"
} }

// Log an activity:
{ "action": "create_item", "post_type": "mcp_ai_crm_activity", "fields": {
  "title": "Discovery call with Jane Smith (Lead #12400)",
  "activity_type": "call", "related_type": "lead", "related_id": "12400",
  "due_date": "2026-08-14"
} }
```

### Updating records

```json
// Qualify a lead:
{ "action": "update_item", "post_type": "mcp_ai_lead", "item_id": 12398,
  "fields": { "lead_status": "qualified", "lifecycle_stage": "sql" } }

// Move a deal through pipeline stages:
{ "action": "update_item", "post_type": "mcp_ai_deal", "item_id": 12327,
  "fields": { "pipeline_stage": "proposal", "win_probability": "0.5",
  "expected_close_date": "2026-09-15", "amount": "25000" } }
```

### Bulk operations

```json
// Bulk create leads from a CSV import:
{ "action": "bulk_create", "post_type": "mcp_ai_lead", "items": [
  { "title": "Alice Brown", "first_name": "Alice", "last_name": "Brown",
    "email": "alice@example.com", "source": "csv_import", "lead_status": "new" },
  { "title": "Bob Wilson", "first_name": "Bob", "last_name": "Wilson",
    "email": "bob@example.com", "source": "csv_import", "lead_status": "new" }
] }
```

### Deleting records

```json
// Delete a lead (prefer disqualifying instead — see Critical Rules):
{ "action": "delete_item", "post_type": "mcp_ai_lead", "item_id": 12398 }
```

**⚠️ Warning:** Deleting a record is permanent. Consider using `update_item` to
change `lead_status` to `"disqualified"` instead of deleting, to preserve audit history.

## Common Workflows

### Lead qualification workflow

```
1. List new leads:   list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "new"}])
2. Review BANT:      Check bant_assessment scores. Prioritize high Need + Timeline.
3. Create activity:  create_item(mcp_ai_crm_activity, activity_type: "call")
4. Update lead:      update_item(mcp_ai_lead, lead_status: "contacted")
5. If qualified:     update_item(mcp_ai_lead, lead_status: "qualified", lifecycle_stage: "sql")
                     create_item(mcp_ai_deal, lead_id: <lead_id>, pipeline_stage: "qualification")
```

### Deal pipeline management

```
1. Find stalled deals:  list_items(mcp_ai_deal, filters per pipeline_stage)
2. Check activities:    list_items(mcp_ai_crm_activity, filters: [{key: "related_id", value: "<deal_id>"}])
3. Advance stage:       update_item(mcp_ai_deal, pipeline_stage: <next_stage>, win_probability: <new_prob>)
4. Log activity:        create_item(mcp_ai_crm_activity, activity_type: "note", content: "<disposition>")
```

### Pipeline stage progression with win probabilities

| Stage | Win Probability | Typical Actions |
|---|---|---|
| `inquiry` | 5% | Initial contact, needs discovery |
| `scoping` | 10% | Define requirements, budget range |
| `qualification` | 25% | BANT/MEDDIC confirmed, champion identified |
| `proposal` | 50% | Proposal sent, economic buyer engaged |
| `negotiation` | 75% | Terms negotiation, legal review |
| `engagement_signed` | 90% | Contract signed, onboarding begins |
| `won` | 100% | Revenue recognized |
| `lost` | 0% | Closed-lost with reason |

### Building a company profile

```
1. Research company:  Use deep_research or web_search_validated for company info.
2. Create company:    create_item(mcp_ai_company, with industry, size, website, status).
3. Link lead:         update_item(mcp_ai_lead, adding _company_id reference to the company post ID).
4. Add contacts:      create_item(mcp_crm_contacts) for key personas at the company.
```

### Activity logging (call disposition)

```
After every call/meeting:
1. create_item(mcp_ai_crm_activity, activity_type: "call"|"meeting"|"email")
2. Set title:         "<Action> with <Contact Name> (<Entity> #<ID>)"
3. Set related_type:  "lead" | "deal" | "company" | "customer"
4. Set related_id:    The entity post ID
5. Set content:       Summary of the conversation, next steps, disposition
6. Set due_date:      For follow-up tasks (activity_type: "task")
```

### Pipeline triage

```
Weekly pipeline review:
1. list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "new"}])
   → Identify high-score leads (lead_score >= 60) for immediate follow-up.
   
2. list_items(mcp_ai_deal, filters: [{key: "pipeline_stage", value: "qualification"}])
   → Find deals stuck in qualification for 2+ weeks — they need a champion.
   
3. list_items(mcp_ai_crm_activity, filters: [{key: "activity_type", value: "task"}])
   → Check for overdue follow-up tasks (due_date < today).
   
4. list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "disqualified"}])
   → Review disqualified leads — some may be worth re-engaging.
```

### Searching across CRM

```json
// Find all leads from a specific company domain:
{ "action": "list_items", "post_type": "mcp_ai_lead", "search": "@cbiz.com" }

// Find all activities for a lead:
{ "action": "list_items", "post_type": "mcp_ai_crm_activity",
  "filters": [{ "key": "related_type", "value": "lead" },
              { "key": "related_id", "value": "12398" }] }
```

## Critical Rules

- **Always use `get_schema` first** before creating or updating a record to verify available field keys and types.
- **Lead scoring is automated** — the `lead_score` and `bant_assessment` are populated by the CRM engine. Manual overrides should be rare and documented.
- **Never delete leads** — use `lead_status: "disqualified"` to preserve audit trail and prevent re-import of the same contact.
- **Activities are the audit trail** — log every meaningful interaction (call, email, meeting, note) with `related_type` and `related_id`.
- **Deal pipeline stages are sequential** — don't skip stages. Each stage transition should have an activity log.
- **`deal_owner` is a WordPress user ID** — ensure the user exists and has appropriate CRM capabilities.
- **`win_probability` is a float stored as string** — use `"0.1"` not `0.1` in JSON.
- **BANT `evidence` is semicolon-delimited** — the engine parses email content for keyword evidence. When manually setting, use `"keyword1; keyword2; "` format.
- **Bulk operations (`bulk_create`) are for imports** — each item must be a complete fields object. Existing records with matching IDs will be overwritten.
- **Support tickets (`mcp_ai_ticket`) are SLA-tracked** — create them for customer issues, not sales inquiries.

## Common Mistakes

```
WRONG — deleting a lead instead of disqualifying
{ "action": "delete_item", "post_type": "mcp_ai_lead", "item_id": 12398 }

RIGHT — disqualify to preserve history
{ "action": "update_item", "post_type": "mcp_ai_lead", "item_id": 12398,
  "fields": { "lead_status": "disqualified" } }

WRONG — creating a deal without linking to a lead
{ "action": "create_item", "post_type": "mcp_ai_deal",
  "fields": { "deal_name": "Some Deal", "pipeline_stage": "qualification" } }
// Missing lead_id — the deal has no source traceability.

RIGHT — always link deals to their source lead
{ "action": "create_item", "post_type": "mcp_ai_deal",
  "fields": { "lead_id": "12398", "deal_name": "CBIZ - Audit Automation",
  "pipeline_stage": "scoping", "amount": "0", "currency": "USD", "deal_owner": "1",
  "win_probability": "0.1" } }

WRONG — logging an activity without related_type or related_id
{ "action": "create_item", "post_type": "mcp_ai_crm_activity",
  "fields": { "title": "Call with prospect", "activity_type": "call" } }
// This activity is orphaned — it can't be found when viewing the lead/deal.

RIGHT — always link activities to their parent entity
{ "action": "create_item", "post_type": "mcp_ai_crm_activity",
  "fields": { "title": "Discovery call with Jill Scher (Lead #12398)",
  "activity_type": "call", "related_type": "lead", "related_id": "12398" } }

WRONG — skipping pipeline stages
// Moving from "inquiry" directly to "proposal" with no scoping or qualification.
// The pipeline history should reflect the actual sales process.

RIGHT — advance stage-by-stage with activity log
1. update_item: pipeline_stage: "scoping"
2. create_item(activity): "Scope of work discussed"
3. update_item: pipeline_stage: "qualification"
4. create_item(activity): "BANT confirmed, champion identified"
5. update_item: pipeline_stage: "proposal"

WRONG — setting win_probability to 0 or 1 prematurely
// Win probability should reflect real pipeline stage, not optimism/pessimism.

WRONG — searching with filters that use meta keys not in the schema
// Some meta fields may be added dynamically. Always call get_schema first
// to confirm which fields are registered and filterable.
```

## Cross-References

- Run `design-deep-research` to research target companies before creating company profiles.
- Run `design-web-research` for quick company lookups and competitive intelligence.
- Run `design-pro-workflow-builder` to automate CRM workflows (lead scoring, auto-assignment, stage progression).
- Run `design-pro-schedule-manager` to schedule recurring CRM tasks (pipeline reviews, follow-up reminders).
- Run `design-document-generation` to create proposals, SOWs, and invoices from deal data.
- Run `wp-security-audit` on any CRM automation callbacks — CRM data is sensitive and must be access-controlled.

## What This Skill Does NOT Cover

- Email integration details (Gmail/Outlook sync) — use `search_gmail` for inbox queries.
- Remote WordPress CRM access — use `nv_oos_console_agent_remote_wp_connection` for multi-site CRM.
- Paper Store integration — use `paper_store_*` tools for research-backed company profiles.
- ERP integration (EZuite) — use `ezuite_erp` / `ezuite_erp_get_products` for ERP-connected CRM data.
- CRM workflow rule configuration — use `toolkit_cpt` with `post_type: "mcp_ai_crm_wf_rule"` and the `design-pro-workflow-builder` skill.
- Sequence automation — use `toolkit_cpt` with `post_type: "mcp_ai_sequence"`.

## References

- NV oOS Pro Toolkit CRM admin page: `/wp-admin/admin.php?page=nvoos-pro-toolkit-crm`
- `toolkit_cpt` MCP tool — the primary interface for all CRM operations.
- BANT framework: [blog.hubspot.com/sales/bant](https://blog.hubspot.com/sales/bant)
- MEDDIC framework: [meddic.co](https://meddic.co)