crm-builder

What this skill does

# CRM Builder Skill

## What This Skill Does

This skill defines how to build a **CRM tool** — a system for managing contacts, companies, deals, and the relationships between them.

CRM is structurally different from CPQ and trades-builder:
- **CPQ / Trades** = one record moves through sequential stages (stepper navigation)
- **CRM** = multiple entity types with relationships between them (entity navigation)

The left sidebar uses a **navigator pattern** (Contacts, Companies, Deals, Pipeline, Activities) — NOT a stepper. Users switch between entity views, not sequential stages.

**Common verticals:** sales teams, consulting firms, agencies, professional services, real estate, recruiting, B2B services, any business that tracks relationships and deals.

The builder reads this skill, reads the DOMAIN.md for the specific business terminology and pipeline stages, and generates a working prototype with the customer's actual entities, fields, and workflow.

## When to Use This Skill

Use this skill when the transcript or DOMAIN.md contains these signals:

| Signal | Examples |
|---|---|
| **Contact/people tracking** | "customer data is everywhere," "can't find who we talked to," "contacts in spreadsheets" |
| **Sales pipeline** | "deals," "opportunities," "pipeline," "stages," "won/lost" |
| **Follow-up tracking** | "follow-ups fall through the cracks," "no one knows who called last" |
| **Relationship management** | "referrals," "who knows who," "account management" |
| **Lead management** | "leads from website," "inbound inquiries," "lead source tracking" |

**Do NOT use this skill for:**
- Product configuration with pricing → use cpq-builder
- Construction/trades project tracking → use trades-builder
- Inventory and stock management → use erp-builder (future)

---

## Template Contract

Before you start building, understand what the template gives you and what this skill adds. This is the contract:

**The template (`app/layouts/MainLayout.tsx`) ships with:**
- `SidebarProvider`, `Sidebar`, `SidebarContent`, `SidebarInset`, `SidebarTrigger` — already wired
- `SidebarContent` is **empty** — this is your landing zone
- One brand slot in the header (logo placeholder + company name)
- `ModeToggle` and user menu in the header's right cluster

**This skill fills:**
- `SidebarContent` — with entity navigation (Pipeline, Contacts, Companies, Deals, Activities), quick filters, and recent records (see Layout Pattern below)
- The brand slot in the header — with the client's logo and company name from DOMAIN.md
- The header's right cluster — adds a role switcher `DropdownMenu` before the existing user menu, plus a global search input if there's room
- The `<Outlet />` in `<main>` — via route components for each entity view (Pipeline is default)

**This skill does NOT:**
- Add a second `Sidebar` component. There is one sidebar.
- Put a brand tile inside `SidebarContent`. Brand lives in the header only.
- Rewire `SidebarProvider` or replace the collapsible behavior. Use what's there.
- Build a stepper. CRM uses entity navigation — parallel views, not sequential stages.
- Collapse the detail view into a popover or modal by default. List/detail is a full-page pattern (list view → click → detail view in the main content area).

If you find yourself wanting to restructure `MainLayout.tsx`, stop — the answer is almost always to fill `SidebarContent` instead.

---

## Section Definitions

The CRM tool has **FIVE sections**. Unlike CPQ/trades-builder, these are NOT sequential stages — they are parallel entity views. Users navigate between them freely.

### Section 1: Pipeline

**What it does:** Visual board view of deals moving through stages.

**Display:**
- Kanban-style columns, one per pipeline stage from DOMAIN.md
- If DOMAIN.md does not define stages, use: Lead → Qualified → Proposal → Negotiation → Closed Won / Closed Lost
- Each deal item shows: deal name, company, value, assigned to, days in stage
- Drag-and-drop between columns (or click to move stage)
- "Add deal" button on each column
- Filter by assigned person, date range, or deal value

**If no pipeline stages exist in DOMAIN.md**, use the defaults above. The customer refines them after seeing the prototype.

### Section 2: Contacts

**What it does:** List/detail view of people.

**List view:**
- Table or lightweight list of contacts
- Columns: name, email, phone, company, last activity, tags
- Search and filter
- "Add contact" button

**Detail view (clicking a contact):**
- Contact detail: name, email, phone, company (linked), role/title, source, notes
- Activity timeline below: calls, emails, meetings, notes — most recent first
- Linked deals: list of deals associated with this contact
- "Log activity" button: quick-add a call, email, meeting, or note with date and description

**Fields from DOMAIN.md:**
- Entity Registry → Contact entity fields become the contact detail fields
- Terminology Glossary → exact field names and labels
- If DOMAIN.md doesn't define contact fields, use: name, email, phone, company, role, source, notes

### Section 3: Companies

**What it does:** List/detail view of organizations.

**List view:**
- Table of companies
- Columns: company name, industry, contacts count, deals count, total deal value
- Search and filter
- "Add company" button

**Detail view (clicking a company):**
- Company detail: name, industry, size, website, address, notes
- Contacts tab: list of people linked to this company
- Deals tab: list of deals linked to this company
- Activity timeline: aggregated from all contacts at this company

**Fields from DOMAIN.md:**
- Entity Registry → Company/Account entity fields
- If not defined: name, industry, size, website, address, notes

### Section 4: Deals

**What it does:** List/detail view of deals/opportunities.

**List view:**
- Table of deals
- Columns: deal name, company, contact, value, stage (badge), close date, assigned to
- Sort by value, stage, close date
- Filter by stage, assigned person
- "Add deal" button

**Detail view (clicking a deal):**
- Deal detail: name, value, stage (selectable dropdown), expected close date, probability, assigned to
- Linked contact and company (clickable links)
- Activity timeline specific to this deal
- Notes section
- "Mark as Won" / "Mark as Lost" action buttons when in final stages

**Stage progression:**
- Deal stage is a `Select` dropdown populated from DOMAIN.md pipeline stages
- Changing the stage updates the Pipeline board view automatically
- Won/Lost are terminal stages — show win/loss reason field when selected

### Section 5: Activities

**What it does:** Chronological feed of all activities across the CRM.

**Display:**
- Timeline/feed view, most recent first
- Each activity shows: type icon (call/email/meeting/note), description, linked contact, linked deal, date, logged by
- Filter by activity type, date range, person
- "Log activity" button at top

**Activity types:** Call, Email, Meeting, Note, Task. Use icons to distinguish.
- If DOMAIN.md defines different activity types, use those instead.

## Layout Pattern

The CRM tool uses a **two-panel layout** (left sidebar + main content) by default. A right sidebar appears contextually when viewing a record detail.

**This is NOT a stepper layout.** The left sidebar is entity navigation, not sequential stages.

### Left sidebar (always visible, collapsible)

The template ships `SidebarProvider`, `Sidebar`, `SidebarContent`, and `SidebarTrigger` already wired in `app/layouts/MainLayout.tsx`. `SidebarContent` is empty — that's the slot this skill fills with entity navigation. Do not re-wire the sidebar, do not add a second `Sidebar` component, and do not put a brand tile inside it. Brand identity lives in the header only (see Template Contract above).

**Sidebar heading:** Use a contextual label like "CRM" or the business name + "CRM" — not a workflow description. If the business name is short, "[Business] CRM" reads naturally; if it's long, just "CRM" is fine. The hea