Domain Modeling
Actively build and sharpen the active project's domain model while designing. This
is the discipline of challenging terms, testing relationships with concrete cases,
and capturing settled knowledge when it crystallizes.
Project Artifacts
Use <repository-root>/.agents/projects/<project>/ for all project artifacts. Resolve
the repository root before reading or writing; never use a global agent-installation
directory. Create only the files that have content to hold:
CONTEXT.md holds a concise project description, confirmed facts, tracker choice,
reusable non-secret configuration references, relevant links, and domain language.LINKS.md holds Jira, GitHub, Confluence, repository, and other external links.adr/NNNN-slug.md holds a durable architectural decision.
Keep CONTEXT.md factual and concise. It is neither a specification nor a scratch
pad. A glossary entry defines a project-specific term in one or two sentences and
may name near-synonyms under _Avoid_.
During The Session
Read the active project's context and links before proposing terminology or a
decision. If a user statement conflicts with them or with the codebase, surface
the contradiction for resolution.
Done when the current discussion starts from the existing project facts.
Challenge vague or overloaded terms. Propose one canonical term, then stress-test
relationships with concrete edge-case scenarios before recording them.
Done when each resolved domain concept has an unambiguous definition.
Update CONTEXT.md and LINKS.md inline as facts, terminology, tracker details,
configuration references, and links become confirmed. Never store secret values;
record only a variable name, owner, purpose, or retrieval location.
Done when reusable knowledge is recorded without duplicating implementation plans.
Offer an ADR only when the decision is hard to reverse, surprising without
context, and the result of a real trade-off. Number it after the highest existing
project ADR and state the context, decision, and reason concisely.
Done when every qualifying decision is preserved under .agents/projects/<project>/adr/.
1---2name: domain-modeling3description: Build and sharpen a project's domain model. Use when terminology, project facts, or durable design decisions must be clarified and recorded, or when another skill needs to maintain them.4---56# Domain Modeling78Actively build and sharpen the active project's domain model while designing. This9is the discipline of challenging terms, testing relationships with concrete cases,10and capturing settled knowledge when it crystallizes.1112## Project Artifacts1314Use `<repository-root>/.agents/projects/<project>/` for all project artifacts. Resolve15the repository root before reading or writing; never use a global agent-installation16directory. Create only the files that have content to hold:1718- `CONTEXT.md` holds a concise project description, confirmed facts, tracker choice,19 reusable non-secret configuration references, relevant links, and domain language.20- `LINKS.md` holds Jira, GitHub, Confluence, repository, and other external links.21- `adr/NNNN-slug.md` holds a durable architectural decision.2223Keep `CONTEXT.md` factual and concise. It is neither a specification nor a scratch24pad. A glossary entry defines a project-specific term in one or two sentences and25may name near-synonyms under `_Avoid_`.2627## During The Session28291. Read the active project's context and links before proposing terminology or a30 decision. If a user statement conflicts with them or with the codebase, surface31 the contradiction for resolution.3233 Done when the current discussion starts from the existing project facts.34352. Challenge vague or overloaded terms. Propose one canonical term, then stress-test36 relationships with concrete edge-case scenarios before recording them.3738 Done when each resolved domain concept has an unambiguous definition.39403. Update `CONTEXT.md` and `LINKS.md` inline as facts, terminology, tracker details,41 configuration references, and links become confirmed. Never store secret values;42 record only a variable name, owner, purpose, or retrieval location.4344 Done when reusable knowledge is recorded without duplicating implementation plans.45464. Offer an ADR only when the decision is hard to reverse, surprising without47 context, and the result of a real trade-off. Number it after the highest existing48 project ADR and state the context, decision, and reason concisely.4950 Done when every qualifying decision is preserved under `.agents/projects/<project>/adr/`.
akathecoder