Step 2: Domains

With business context written, decide who the audiences are.

---

Why Define Domains Now?

Domains determine where context files live and who they apply to. Knowing the audiences before writing task instructions and behavior files means you write them for the right audience from the start — rather than writing generic files and retrofitting them later.

At Grove, two audiences ask questions: the analytics team and the customer success team. They care about different things, use different language, and sometimes need different definitions of the same concept.

---

What Is a Domain?

A domain is a named audience or business unit with its own view of the data. Different domains can have different context files, different examples, and — when necessary — different feature definitions.

The key rule: Entities are always defined in the main domain (default). Domains customize how context is presented, not the entity structure itself. If two audiences need different feature definitions for the same entity, that is when a custom domain gets its own entity YAML.

---

The Main Domain (default)

Every Lynk project has a main domain called default. It contains:

• All entity YAML files

• The canonical feature definitions

• Business-wide knowledge, glossary, and behavior files

Every other domain is an overlay on top of default. If a custom domain does not define something, the agent falls back to default.

---

When to Create a Custom Domain

Create a custom domain when an audience needs:

• Different context — the customer success team needs guidance about at-risk flags, renewal dates, and escalation signals that the analytics team does not need

• Different examples — CSM questions focus on individual account risk; analytics questions focus on aggregate metrics

• Different feature definitions — only when the same feature means something genuinely different to this audience (rare)

Do not create a domain to organize files. If the definitions and context are the same, one domain is enough.

---

Grove Example: Two Domains

Domain	Audience	What it has
default	Analytics and data engineering	All entity definitions, business-wide knowledge, glossary, SQL rules, output format
cs	Customer success team	CS-specific knowledge about at-risk accounts, renewal focus, CSM question examples

The cs domain does not need its own customer.yml — it uses the same feature definitions. It gets a cs_knowledge.md with CS-specific context and its own evaluations.yml with CSM-oriented test cases. No entity YAML overrides needed.

---

Domain Folder Structure

.lynk/
├── default/                                       # All entity definitions live here
│   ├── entities/
│   │   ├── customer.yml
│   │   ├── customer/
│   │   │   ├── customer__knowledge.md
│   │   │   └── customer__task_inst__text_to_sql.md
│   │   ├── subscription.yml
│   │   └── subscription/
│   │       ├── subscription__knowledge.md
│   │       └── subscription__task_inst__text_to_sql.md
│   ├── entities_relationships.yml
│   ├── domain_context/
│   │   ├── grove_knowledge.md
│   │   └── default__task_inst__text_to_sql.md
│   ├── grove_glossary.md
│   ├── evaluations.yml
│   └── agent/
│       ├── clarification_policy.md
│       └── output_format.md
└── cs/                                            # Only what differs from default
    ├── domain_context/
    │   └── cs_knowledge.md
    └── evaluations.yml

Rules for custom domain folders:

• Only add entity YAML in a custom domain if feature definitions must differ from default

• Context files in a custom domain apply only to that domain and shadow their default equivalents

• entities_relationships.yml lives only in default — relationships are shared across domains

• Glossary and behavior files scoped to domain: "*" apply to all domains

---

The cs Domain Knowledge File

Location: .lynk/cs/domain_context/cs_knowledge.md

---
type: knowledge
domain: "cs"
---

## Who Uses This Domain

Customer success managers (CSMs) at Grove use this view to monitor account health, prioritize outreach, and manage renewal conversations. Typical questions: which accounts are at risk, which renewals are coming up, which customers have low NPS.

## What CSMs Care About

- At-risk flags: NPS below 6 or no login in 60 days
- Pending cancellations: subscriptions with a scheduled cancellation before renewal
- Renewal timeline: `current_period_end` on the subscription entity is the renewal date
- Plan type: enterprise accounts get priority CSM attention

## How CSMs Count "Active"

For CSM purposes, "active" means the account has status = 'active' AND has logged in within the past 30 days. This is more restrictive than the analytics definition (status = 'active' alone). When a CSM asks for active accounts, apply both conditions.

This behavioral rule belongs in the knowledge file, not in task instructions. The agent reads the knowledge file when planning a query in the cs domain and applies this definition automatically. Task instructions are the right place when you need a specific SQL pattern — here, the plain-English definition is enough.

---

Key Point

Entities are defined once in default and shared. Domains are the mechanism for customization without duplication. Before creating a custom domain entity YAML, ask: does this audience need a different definition of this feature, or just different context about it?

If the answer is "different context" — add a context file to the custom domain folder. If the answer is "different definition" — then a custom entity YAML in that domain is warranted.