Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
Plan — Dynamic fields (build)
Build instructions for the agent implementing dynamic fields on companies, contacts and deals.
dynamic-fields.md is the design record — it owns the
schema and the reasoning behind every decision. This document is the build
order: what to type, where, and in what sequence. Where they disagree, the
design doc wins on why and this one wins on how.
Two constraints govern everything below.
- The Paper design is fixed. Match it exactly. Do not improve it, round it, or reword it.
- shadcn components only. No hand-rolled buttons, inputs, switches, chips or
menus. If a component does not exist, add it to
packages/uiwith the shadcn CLI or add a variant there — never at the call site.
0. Read before you type, and say what you read
| Before touching | Read |
|---|---|
| Anything | AGENTS.md, design.md, dynamic-fields.md |
apps/api |
api.md, .agents/skills/nestjs-trpc/SKILL.md |
packages/db |
.agents/skills/prisma-database-setup/SKILL.md |
apps/app |
apps/app/AGENTS.md → then the relevant guide in apps/app/node_modules/next/dist/docs/01-app/ |
| URL state | .agents/skills/nuqs/SKILL.md |
| Any UI | .agents/skills/shadcn/SKILL.md and rules/styling.md, rules/composition.md, rules/forms.md |
apps/agent |
.agents/skills/eve/SKILL.md → then apps/agent/node_modules/eve/docs/README.md |
| A telemetry event | telemetry.md |
1. The design
Paper file CRM, page crm - lewis:
https://app.paper.design/file/01KZ72S23CM00WXN6S1MP68M03/5-1
| Artboard | What it specifies |
|---|---|
/companies?record=company:abcd |
Cog in the DETAILS header; custom fields inline; a pending agent suggestion |
/contacts?record=contact:abcd |
Cog placement only |
/deals?record=deal:abcd |
Cog placement only |
…&manageFields=company |
The fields sheet — list state |
…&manageFields=company (first run) |
Empty state |
…&manageFields=company&manageField=new |
Create a field |
…&manageFields=company&manageField=runs_on |
Edit a field, with coverage |
…&manageFields=company&manageField=runs_on (archive) |
Archive confirmation |
Take values from the file, not from screenshots. get_jsx,
get_computed_styles, get_node_info. A screenshot will not tell you whether a
gap is 8 or 10.
Every user-visible string is in §7. They are final.
2. Schema
Copy the Prisma models from dynamic-fields.md §3
verbatim — FieldEntity, FieldType, FieldDefinition, FieldOption,
FieldValue. That section also explains why values are typed columns rather than
JSON, why one value table carries three nullable FKs, and why key is immutable.
Do not redesign it; if you think it is wrong, say so before writing the
migration.
On top of that:
- Migration name:
dynamic_fields. Run throughbun run db:migrateinpackages/db— neverdb:pushfor a schema that ships. - Add the back-relations on
Company,ContactandDeal(fieldValues FieldValue[]). agentFilled Boolean @default(true)— the default is the feature. Seedynamic-fields.md§5.- No
organizationId. Single tenant.
3. @crm/db/fields — the shared core
Everything else in this plan is a caller of this module. It is what makes the feature API-driven and agent-driven without two implementations drifting apart.
Create packages/db/src/fields.ts and add "./fields": "./src/fields.ts" to the
exports map in packages/db/package.json — the same shape as
@crm/db/currency and @crm/db/workspace, which are the precedents.
It owns:
FIELD_TYPESand the type→storage-column map (TEXT→text,NUMBER→number,DATE→date,CHECKBOX→bool,SELECT→optionId,USER→userId, …).fieldKeyFromLabel(label)— slug, collision-checked by the caller against@@unique([entity, key]).valueSchemaFor(definition)— returns the Zod schema for one field's value.readValues(entity, recordId)/writeValues(tx, entity, recordId, values)— the only two functions that touchFieldValue.serializeField(definition)— the wire shape used by tRPC and by agent tools, so both see identical field metadata.
Rule: no field logic anywhere else. Not in a router, not in a service, not in a component, not in an eve tool. A validator written twice is a bug with a delay on it.
4. API — apps/api/src/fields/
Four files, mirroring apps/api/src/companies/:
fields.contracts.ts, fields.router.ts, fields.service.ts, fields.module.ts.
Register FieldsModule in app.module.ts imports; FieldsRouter must be in
the module's providers or it silently does not exist at runtime.
@Router({ alias: "fields" }) + @UseMiddlewares(AuthMiddleware) on the class.
No middleware means public — there is no other guard.
| Procedure | Input | Notes |
|---|---|---|
fields.list |
{ entity, includeArchived? } |
Definitions with options, position order |
fields.byKey |
{ entity, key } |
For the editor screen |
fields.create |
label, type, options, agentFilled, agentBrief, placement |
Key derived from label |
fields.update |
id + same, minus key | Reject a key change with BAD_REQUEST |
fields.reorder |
{ entity, ids } |
One transaction, positions rewritten from the array |
fields.archive / fields.restore |
{ id } |
Archive is the normal path |
fields.delete |
{ id } |
Loud, and separate from archive |
fields.backfill |
{ id } |
Writes one AgentTask, kind: "field-backfill" — never one per record |
Rules that are not optional:
- Routers are thin. Zod in, service call out. Prisma lives in the service.
- Values do not get their own router. They ride the record procedures:
companies.byIdgainsfields,companies.updateacceptsfields: Record<key, value>. Same for contacts and deals. One write, one invalidation, and the existing inline editors keep their mutation. - Services throw Nest's
HttpExceptionfamily;DomainErrorMiddlewaremaps them. - Regenerate and commit
src/generated/server.ts(bun run trpc:generate). If the app cannot seetrpc.fields.*, this is why. - Tests:
apps/api/test/fields.spec.ts,bun:test, modelled onapps/api/test/bulk.spec.ts(real database,TEST_RUN_ID-suffixed data, cleaned up inafterAll). Cover: key collision, key immutability, value coercion per type, archive keeps values, delete cascades, reorder is atomic.
5. Agents — apps/agent
The API is one caller of @crm/db/fields; the agent is the other. Add
apps/agent/agent/lib/fields.ts as a thin wrapper, in the shape of
lib/facts.ts, then these tools in apps/agent/agent/tools/:
| Tool | Does |
|---|---|
list_fields |
Every field for an entity with its key, type, options and brief — so the agent can discover the schema instead of being told it |
set_field_value |
Write a value the agent is certain of |
propose_field_value |
Offer a value with evidence — routes through the fact/proposal path, not a direct write |
create_field / update_field |
Manage definitions, so "add a field for X" works in chat |
archive_field |
Behind lib/approval.ts. Destructive schema changes get a human |
Constraints:
- The
agentBriefis the instruction the agent works from.list_fieldsmust return it. - Tool descriptions carry the same voice as the existing tools — read
record_fact.tsandsearch_crm.tsfirst. - Nest still writes rows, not intelligence.
fields.backfillwrites anAgentTask; the agent decides fan-out, batching and priority. - Missing capability ⇒ missing capability, never a throw.
MCP later, for free. Every capability is a tRPC procedure over
@crm/db/fields, and every tool is a thin call to the same module. An MCP server
is then a mechanical wrapper over fields.* with no new logic. That only stays
true if you keep logic out of the tools. Do not build MCP now.
6. App — apps/app
URL state (nuqs)
Two params, added to the existing shared parser object in
apps/app/components/crm/record-sheet/record-stack.ts — do not start a second
parser file:
fields: parseAsStringLiteral(RECORD_KINDS),
field: parseAsString,
fieldsis the entity whose fields are open;fieldis either the create sentinelnewor a field key. Add nothing else to the pasted lines — AGENTS.md forbids code comments, and these go straight intorecord-stack.ts.newis a reserved key, held back byRESERVED_KEYSinpackages/db/src/fields-shape.ts, so a field labelled New slugs tonew_fieldand its editor can still be opened. Never let the sentinel and a derivable key collide.- Both cleared by the existing
write()alongsidetab,add,thread. useQueryStatesfor the pair;nullto clear;history: "replace"for sheet state, matching whatrecord-stack.tsalready does.- The cog sets
fieldsto the record's own kind, so the sheet opens on the entity you came from.
Components — use these, build nothing
| Element in Paper | Use |
|---|---|
| Fields sheet shell | DetailSheet (components/detail-sheet.tsx) at a new md size |
| Sheet header, back + title + close | DetailSheetHeader — it already does back-at-left, close-at-right |
| Entity switcher | Tabs / TabsList / TabsTrigger, default variant |
| Standard / Archived disclosure rows | Collapsible — add it: bunx --bun shadcn@latest add collapsible in packages/ui |
Type chip (Select, Date, Number, Checkbox) |
Badge — add it, then add a mono variant in packages/ui |
| Row overflow menu | Button variant="ghost" size="icon-xs" + DropdownMenu |
| Drag handle | Button variant="ghost" size="icon-xs" carrying the dnd listeners, Carbon Draggable icon |
| Form labels and helper text | Field, FieldLabel, FieldDescription, FieldGroup (packages/ui/src/components/field.tsx) |
| Label / brief inputs | Input, Textarea |
| Type picker | Select |
| Option rows | InputGroup with a leading handle addon and a trailing remove Button |
| "Add option" | Button variant="ghost" size="sm" |
| Agent toggle | Switch |
| Placement toggles | Checkbox + FieldLabel |
| Footer actions | Button (primary) and Button variant="outline" |
| Coverage block | Mirror DetailSheetPending's muted panel; dot is StatusIndicator |
| Archive confirm | AlertDialog, action button destructive |
| Empty state | Empty / EmptyHeader / EmptyMedia / EmptyTitle / EmptyDescription / EmptyContent |
| The cog itself | Button variant="ghost" size="icon-sm", Carbon Settings, in DetailSheetSection's existing action slot |
Three additions to packages/ui, because that is where they belong:
mdsheet size.sheetContentVariantshassm | lg | xl | 2xland nothing near 460px. Addmd: "data-[side=left]:sm:max-w-[460px] data-[side=right]:sm:max-w-[460px]". The width comes from the artboards, and 1:1 outranks landing on a Tailwind step.Badge+ amonovariant for the type chip.SortableListover@dnd-kit/core+@dnd-kit/sortable. The repo has no drag-and-drop library today. The artboards show drag handles on both field rows and option rows, so dragging is in scope and a Move up / Move down menu is not an acceptable substitute here.
EmptyDescription also has no wrap class — add text-balance there so the empty
state does not orphan its last word. Fix it in the component, not at the call
site.
Rendering fields on a record
In company-sheet.tsx (then contacts, then deals), custom fields render inline
inside the existing Details section, after the standard properties, in
position order. No "Custom fields" heading, no separate section.
One map from FieldType to the editor that already exists:
| Type | Component |
|---|---|
TEXT, URL, EMAIL, PHONE |
InlineField (with type) |
LONG_TEXT |
InlineTextArea |
NUMBER |
InlineField |
DATE |
InlineDateField |
SELECT, USER |
InlineSelectField |
CHECKBOX |
Checkbox in a DetailSheetProperty |
Agent-sourced values get SOURCED_VALUE (dotted underline) with SourcedValue
for the hover source. Pending proposals render with the existing Suggestion
component. Both are built — use them, do not restyle them.
Table columns
showOnTable is opt-in per field. A workspace with thirty fields must not get a
thirty-column table. Wire it into the existing column definitions in
companies-table.tsx and friends.
Cache
Add fields(entity?) to CrmCache in apps/app/lib/trpc/cache.ts. A definition
change invalidates fields.list plus every list and record query for that
entity. Value edits keep { settle: "record" } so the inline spinner clears
without waiting for the table. A new mutation adds a call there, not a new list
of keys at the call site.
7. Copy — verbatim
Fields sheet
- Title
Fields - Subtitle
This shapes every company in your CRM.(company / contact / deal) - Tabs
CompaniesContactsDeals Standard fields·8 · reorder and hide onlyCustom fields·Drag to orderArchived·2 · values kept, hidden everywhere- Footer
New field·Order here is the order on the sheet
Empty state
No custom fields yetCreate dynamic fields that your agents can research and pre-fill.New field
Editor
LabelKey·What the API and your agents call it. Set from the label, fixed once saved — renaming the label later never breaks a caller.Let your agents fill this·They propose a value with a source, and never overwrite yours.What counts as an answer·Leave it empty and your agents work from the label and type alone.Type·Select — one of a fixed listOptions·Add optionShow on the company sheet·Offer as a column on the Companies tableCreate field·Cancel·Save changes·Archive
Coverage
Filled on 41 of 64 companiesLast looked 2 days ago · you accepted 38 of 41Fill the rest
Archive dialog
Archive Runs on?Hidden everywhere. Its 41 values are kept.Cancel·Archive field
Never "eve" in the product. It is your agents.
8. Order of work
Each phase ends green — typecheck, lint, tests — before the next begins.
- Schema. Models, migration, back-relations.
bun run db:migrate. @crm/db/fields. Types, key derivation, value schemas, read/write. Unit tests here; it is pure and cheap to test.- API. Contracts, service, router, module, registration. Regenerate and
commit
server.ts.fields.spec.tsgreen. - Values on records.
byIdreturnsfields,updateaccepts them, all three entities. packages/uiadditions. Sheetmd,Badge+ mono,Collapsible,SortableList,EmptyDescriptionbalance.- The sheet. List → empty → create → edit → archive, in that order, checking each against its artboard before moving on.
- The cog and the record rendering. Companies first, then contacts and deals.
- Table columns.
- Agent lib and tools.
9. Do not
- Do not deviate from the artboards, including the copy.
- Do not write a custom button, input, chip, switch or menu.
- Do not override component colours or typography with
className. Layout only. - Do not put field logic in a router, a component or a tool — it goes in
@crm/db/fields. - Do not put a vendor client, scoring or enrichment in
apps/api. - Do not add code comments.
- Do not add a
Co-Authored-Bytrailer. - Do not add a per-package
.env. - Do not hand-edit
apps/api/src/generated/server.ts— regenerate it. - Do not build the MCP server. Keep the seam clean so it stays a wrapper.
- Do not make the agent toggle default off.
10. Decisions already made — do not relitigate
- Agent-first:
agentFilleddefaults true, the brief sits above the type in the editor, and only manual fields are badged.dynamic-fields.md§5. - Archive over delete for definitions, with delete kept as a separate loud action.
- Standard fields appear in the list, reorderable and hideable, never deletable.
- Custom fields render inline in DETAILS with no grouping of their own.
11. Open — decide with Lewis, do not guess
Generalising ContactFact to RecordFact (three nullable FKs plus an
optional fieldId) so agent proposals work for custom fields on all three
entities, instead of a parallel proposal table. ContactFact is contact-only and
keys on field String. Agent-first makes this load-bearing rather than optional,
and it is the one decision that gets more expensive after launch. Raise it before
phase 9 — earlier if phase 1 would touch it.