• Read a structured

  DOMAIN.md

  file at the start of every session
• Use internal terminology and entity names exactly as the business defines them
• Flag gaps in domain understanding inline during work
• Propose structured additions to the domain file for human review
• Never corrupt the knowledge base — all updates are proposed, not auto-applied
• Manage domain knowledge growth through progressive disclosure — loading only what's relevant to the current session

1. Look for DOMAIN.md in the project root (or

   docs/domain/DOMAIN.md

   )
2. If found → check the file structure:
   • Single file (under ~200 lines): Read it completely before doing any work.
   • Index + detail files (split structure): Read the root DOMAIN.md index (Tier 1 — core context). Then determine which Tier 2 detail files are relevant to the current task and load only those. See § Progressive Disclosure.
3. If not found → offer to initialize one using the template at

   assets/templates/DOMAIN.md

4. Confirm to the user: "I've loaded the domain context for [Project Name]. I'm familiar with [N] entities and [N] flows." If in split mode, also note: "I've loaded the core context. I'll pull in detail files as needed for what we're working on."

• Use entity names, terminology, and abbreviations exactly as defined in DOMAIN.md
• When encountering an undefined term or entity, mark it inline:

  [UNKNOWN: <term>]

• When a relationship between entities is unclear, mark it:

  [RELATIONSHIP UNCLEAR: <entity-a> → <entity-b>]

• When a business rule seems to be implied but isn't documented:

  [RULE INFERRED: <description>]

• Do not invent domain facts — use only what is documented or what the user confirms in session
• When working on a specific entity or flow, load its Tier 2 detail file if one exists and hasn't been loaded yet

Review these and copy any confirmed items into your DOMAIN.md

• [EntityName]: [Definition as understood from this session]
  • Attributes: [list]
  • Related to: [other entities]

• [term]

  → [plain definition]

• [Entity A] → [verb] → [Entity B]: [description]

• [Rule description]

• [Question about something ambiguous or unresolved]

• [specific section or entry to update]

The human reviews this, edits as needed, and manually updates DOMAIN.md. This keeps the human as domain authority.

---

• ## Project Overview

  — what it is, who uses it, business goal (5 lines)

• ## Domain Boundaries

  — what's in scope, what's supporting, what's explicitly excluded. Prevents overbuilding.

• ## Terminology Glossary

  — the shorthand table

• ## Entity Registry

  — names and one-liner descriptions only (not full attribute lists, not lifecycle details, not notes). Think of this as a table of contents for the entities.

• ## State Models

  — named enumerations and valid state transitions for entities with statuses or lifecycle stages. The AI must treat these as the only valid values.

• ## Business Rules

  — the hard rules table (BR-001, BR-002, etc.). These are ground truth the AI must always know.

• ## User Roles

  — the roles table

• ## Stakeholder Map

  — named people, their relationship to the system, their key concerns, and when to involve them. Critical for adoption and buy-in.

• ## Open Questions

  — current unresolved items

• ## Detail Files

  — index of Tier 2 files with one-line summaries (see file layout below)

• Full entity specs — attributes, lifecycle, relationships, notes, edge cases (one file per major entity)
• Full flow descriptions — step-by-step process walkthroughs (one file per flow)
• Relationship map — the full entity-to-entity table
• Integration points — external system details

• Changelog — session-by-session history of what was learned
• Resolved questions — historical record of closed open questions
• Data migration notes — vendor catalog details, import procedures
• Vendor-specific details — price sheet structures, portal access notes

1. Read root DOMAIN.md (Tier 1 — always)
      ↓
2. Understand the current task
      ↓
3. Determine which entities/flows are relevant
      ↓
4. Load only those Tier 2 files
      ↓
5. Work — loading additional Tier 2 files if the task expands
      ↓
6. Propose updates — specifying which file each update belongs to

1. Reads root DOMAIN.md (core context — knows all entity names, all business rules)
2. Loads

   docs/domain/flows/pm-renewal.md

   (the relevant flow)
3. Loads

   docs/domain/entities/pm-renewal.md

   (the relevant entity)
4. Does NOT load

   docs/domain/flows/lead-distribution.md

   or

   docs/domain/entities/customer.md

   — not relevant to this task.

• Add to Business Rules: BR-013 — [rule description]

• Add attribute:

  priceAdjustmentPercent

  — annual price increase applied on renewal

• [Full flow description to create]

• [Session summary entry]

undefined

MAJOR.MINOR

• MAJOR increments when the fundamental scope changes (new business process, major entity restructure, domain boundary shift)
• MINOR increments on every approved update (new entities, new rules, flow adjustments, stakeholder additions)

> **Version:** 1.5
> **Last updated:** 2026-04-06 (Session 30)
> **Changes:** +Commission Report entity, +BR-013–015, updated Quote-to-Close flow

1. Increment the version number (MINOR +1)
2. Update the "Last updated" date and session reference
3. Update the "Changes" line with a brief summary
4. Append an entry to the Changelog section

your-project/
├── DOMAIN.md                          ← Tier 1: Core index (always loaded)
├── docs/
│   └── domain/
│       ├── entities/                  ← Tier 2: One file per major entity
│       │   ├── quote.md
│       │   ├── customer.md
│       │   ├── product.md
│       │   └── ...
│       ├── flows/                     ← Tier 2: One file per business process
│       │   ├── quote-to-close.md
│       │   ├── pm-renewal.md
│       │   └── ...
│       ├── relationships.md           ← Tier 2: Full relationship map
│       ├── integrations.md            ← Tier 2: External system details
│       └── archive/                   ← Tier 3: Historical records
│           ├── changelog.md
│           └── resolved-questions.md
└── ... (rest of your project)

• Tier 1 sections in full (Project Overview, Domain Boundaries, Glossary, Entity names table, State Models, Business Rules, User Roles, Stakeholder Map, Open Questions)
• A

  ## Detail Files

  index pointing to each Tier 2 file with a one-line summary:

undefined

1. Ask the user 5 seed questions (see

   references/seed-questions.md

   )
2. Use the answers to populate the template
3. Write a draft DOMAIN.md
4. Present it for review before saving

Sessions 1–3:     Single DOMAIN.md, ~60–80 lines      (Tier 1 only)
Sessions 4–10:    Single DOMAIN.md, ~100–200 lines     (Tier 1 + 2 mixed)
Sessions 10+:     Split into index + detail files       (Tier 1 / 2 / 3 separated)
Mature project:   Full three-tier structure with archive

"The domain file is at [N] lines now — it covers [N] entities and [N] flows in detail. Want me to split it into a core index file with separate detail files? Each session would load just the parts relevant to what we're working on, and nothing is lost."

1. Extract Tier 1 content into a slim root DOMAIN.md (~80–120 lines)
2. Move each entity's full description into

   docs/domain/entities/[name].md

3. Move each flow's full description into

   docs/domain/flows/[name].md

4. Move relationship map and integration points into their own Tier 2 files
5. Move changelog into

   docs/domain/archive/changelog.md

6. Add the

   ## Detail Files

   index to the root DOMAIN.md
7. Present the new structure for review before saving

• New developers onboarding
• Future AI sessions (any model, any tool)
• Documentation and specs
• Test case grounding

• assets/templates/DOMAIN.md

  — Blank template to initialize a new domain file

• references/seed-questions.md

  — Questions to ask when bootstrapping a new domain

• references/entity-template.md

  — Template for individual entity files (large projects)

• references/anti-patterns.md

  — Common mistakes to avoid when building domain context