Progressive Domain Crystallization (PDC) Skill

What This Skill Does

This skill enables any AI assistant to build and use a living domain knowledge base for any business application — accumulated incrementally across sessions through a human-AI collaborative protocol.

The AI never "knows" the domain by default. But with this skill, it can:

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

Core Protocol

At Session Start

Look for DOMAIN.md in the project root (or
```
docs/domain/DOMAIN.md
```
)
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.
If not found → offer to initialize one using the template at
```
assets/templates/DOMAIN.md
```
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."

During Work

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

At Session End

Always generate a

## 📋 Proposed Domain Updates

section at the bottom of your final response.

Format it as:

markdown

## 📋 Proposed Domain Updates

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

### New Entities Discovered
- **[EntityName]**: [Definition as understood from this session]
  - Attributes: [list]
  - Related to: [other entities]

### Terminology Clarified
- `[term]` → [plain definition]

### Relationships Identified
- [Entity A] → [verb] → [Entity B]: [description]

### Business Rules Observed
- [Rule description]

### Open Questions
- [ ] [Question about something ambiguous or unresolved]

### Suggested DOMAIN.md Sections to Add/Update
- [ ] [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.

Progressive Disclosure

Domain knowledge files grow over time. A single DOMAIN.md that works well at 80 lines becomes unwieldy at 400. Progressive disclosure keeps the AI focused on what's relevant to the current session without losing access to the full knowledge base.

Three Tiers of Domain Knowledge

Tier	What It Contains	When It's Loaded	Typical Size
Tier 1 — Core	Project overview, terminology glossary, entity names (one-liners only), business rules table, user roles table	Always, at session start	80–120 lines
Tier 2 — Working Context	Full entity descriptions (lifecycle, notes, edge cases), full flow step-by-steps, relationship map, integration points	On demand, when the session touches that entity or flow	30–80 lines per file
Tier 3 — Archive	Changelog, resolved open questions, data migration notes, vendor-specific details	On explicit request, or when reviewing project history	Variable

What Goes in Each Tier

Tier 1 — Core (root DOMAIN.md, always loaded):

```
## 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)

Tier 2 — Working Context (separate files, loaded by task):

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

Tier 3 — Archive (separate files, loaded on request):

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

When to Split: The ~200 Line Rule

A single DOMAIN.md works well for early-stage projects. The trigger to split is simple:

When DOMAIN.md exceeds ~200 lines, propose the split.

Say to the user: "The domain file is getting substantial — [N] lines with [N] entities and [N] flows. Want me to split it into an index file with detail files? This keeps sessions focused on what's relevant without losing anything."

If the user agrees, restructure into the tiered file layout (see below). If they prefer a single file, respect that — it's a preference, not a hard requirement.

How the AI Uses Tiers at Session Start

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

Example: User says "I need to update the PM renewal flow." The AI:

Reads root DOMAIN.md (core context — knows all entity names, all business rules)
Loads
```
docs/domain/flows/pm-renewal.md
```
(the relevant flow)
Loads
```
docs/domain/entities/pm-renewal.md
```
(the relevant entity)

Does NOT load

docs/domain/flows/lead-distribution.md

docs/domain/entities/customer.md

— not relevant to this task.

Proposing Updates in Split Mode

When the domain is split across files, the Proposed Domain Updates section should specify which file each update belongs to:

markdown

## 📋 Proposed Domain Updates

### Update: `DOMAIN.md` (Tier 1 — core)
- Add to Business Rules: BR-013 — [rule description]

### Update: `docs/domain/entities/pm-renewal.md` (Tier 2)
- Add attribute: `priceAdjustmentPercent` — annual price increase applied on renewal

### New File: `docs/domain/flows/engineering-review.md` (Tier 2)
- [Full flow description to create]

### Update: `docs/domain/archive/changelog.md` (Tier 3)
- [Session summary entry]

Versioning

DOMAIN.md includes a version header in its frontmatter. This is the human-readable version — it tells the AI and the team what state the domain knowledge is in.

Version format:

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)

Who increments: The system auto-increments MINOR on each approved update. MAJOR is incremented manually when the team decides the domain has fundamentally expanded.

The version header lives in the DOMAIN.md frontmatter:

markdown

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

On every approved update, the AI must:

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

If the system uses git, the commit message should mirror the Changes line. The version header and git history serve different audiences — the header is for the AI and the business user, git is for engineering.

DOMAIN.md File Structure

See

assets/templates/DOMAIN.md

for the full template.

Single-File Mode (under ~200 lines)

The file uses these top-level sections, all in one file:

Section	Tier	Purpose
`## Project Overview`	1	What the app does, who uses it, primary goals
`## Domain Boundaries`	1	What's in scope, what's supporting, what's excluded
`## Terminology Glossary`	1	Internal jargon mapped to plain definitions
`## Entity Registry`	1 (names) / 2 (details)	Business objects with attributes and descriptions
`## State Models`	1	Valid statuses, types, and state transitions for entities
`## Relationship Map`	2	How entities connect to each other
`## Flow Catalog`	2	Named business processes with step-by-step info flow
`## Business Rules`	1	Constraints, validations, edge cases
`## Integration Points`	2	External systems, APIs, data sources
`## User Roles`	1	Who uses the system and what they can do
`## Stakeholder Map`	1	Named people, their relationship to the system, concerns, involvement timing
`## Open Questions`	1	Unresolved ambiguities — reviewed and cleared over time
`## Changelog`	3	What was learned and when

In single-file mode, all tiers are in one file. This is fine — the tier labels are just annotations that guide the future split.

Split-File Mode (over ~200 lines)

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)

The root DOMAIN.md in split mode contains:

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:

markdown

## Detail Files

| File | Contents |
|------|----------|
| `docs/domain/entities/quote.md` | Quote entity — lifecycle, attributes, status workflow |
| `docs/domain/entities/customer.md` | Customer/Account entity — parent-child, territory assignment |
| `docs/domain/flows/quote-to-close.md` | Full quote lifecycle from opportunity to installation |
| `docs/domain/flows/pm-renewal.md` | PM contract renewal process |
| `docs/domain/relationships.md` | Complete entity relationship map |
| `docs/domain/integrations.md` | Salesforce, Watertight, Procore, vendor portals |
| `docs/domain/archive/changelog.md` | Session-by-session learning history |

Initialization Workflow

If no DOMAIN.md exists, the AI should:

Ask the user 5 seed questions (see
```
references/seed-questions.md
```
)
Use the answers to populate the template
Write a draft DOMAIN.md
Present it for review before saving

The initial file will be well under 200 lines. Start in single-file mode. Split later when it grows.

Growing the Domain Over Time

Each session follows this cycle:

READ DOMAIN.md (+ relevant Tier 2 files if split)
      ↓
DO WORK (flag unknowns inline)
      ↓
PROPOSE UPDATES (specify target file if split)
      ↓
HUMAN REVIEWS & APPROVES
      ↓
HUMAN UPDATES DOMAIN.md (or detail files)
      ↓
(next session reads updated files)

Growth Lifecycle

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

When the file crosses ~200 lines, the AI should proactively offer to split:

"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."

If the user agrees:

Extract Tier 1 content into a slim root DOMAIN.md (~80–120 lines)
Move each entity's full description into
```
docs/domain/entities/[name].md
```
Move each flow's full description into
```
docs/domain/flows/[name].md
```
Move relationship map and integration points into their own Tier 2 files
Move changelog into
```
docs/domain/archive/changelog.md
```
Add the
```
## Detail Files
```
index to the root DOMAIN.md
Present the new structure for review before saving

Over time, the DOMAIN.md becomes the single source of truth for:

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

Reference Files

```
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

domain-context

NPX Install

Tags

SKILL.md Content

Progressive Domain Crystallization (PDC) Skill

What This Skill Does

Core Protocol

At Session Start

During Work

At Session End

Progressive Disclosure

Three Tiers of Domain Knowledge

What Goes in Each Tier

When to Split: The ~200 Line Rule

How the AI Uses Tiers at Session Start

Proposing Updates in Split Mode

Versioning

DOMAIN.md File Structure

Single-File Mode (under ~200 lines)

Split-File Mode (over ~200 lines)

Initialization Workflow

Growing the Domain Over Time

Growth Lifecycle

Reference Files