| name | setting-up-domain-model |
| description | Use when starting the flow in a repo that has no CONTEXT.md / conventions yet, when a term keeps getting used two ways, or when a hard-to-reverse decision was just made and needs recording. Triggers: "set up the repo conventions", "what's our vocabulary", "record this decision", "write an ADR", "the glossary". |
Setup and domain model
Stage contract
- Stage: 0. Setup (once per repo) + cross-cutting upkeep · Kind: method
- Inputs: the repo; whatever domain terms and decisions surface as the flow runs.
- Outputs:
CONTEXT.md (glossary) and docs/adr/ (decision records), created
lazily and kept live.
- Entry gate: first time through the flow in this repo (no CONTEXT.md /
conventions recorded), or a term/decision needs pinning down mid-flow.
- Done when: conventions are recorded; every term the flow relies on has one
canonical definition; every hard-to-reverse decision is an ADR.
- Next: the stage you were routed to — usually the
designing-with-7w3 skill.
- Maintains: it owns CONTEXT.md and docs/adr/; every other stage keeps them live.
Why this exists
The whole flow rests on the invariant the document is the source of truth — design,
spec, and decisions are the record; code realizes them. That invariant needs a concrete
home, or it stays a slogan. These two artifacts are that home:
- CONTEXT.md keeps the vocabulary from drifting. When "user", "account", and
"member" mean the same thing in three files, the design has already started to rot.
One canonical term per concept keeps every later stage — spec, breakdown, reviews —
talking about the same things.
- docs/adr/ keeps the why of hard-to-reverse choices from evaporating. A decision
that isn't recorded gets silently re-litigated or quietly reversed by an agent that
never saw the trade-off.
Create both lazily — only when the first term or the first real decision appears.
An empty CONTEXT.md on day one is ceremony; a stale one is worse than none.
Once-per-repo setup
Do this the first time the flow touches a repo. Keep it to what the flow actually needs:
- Decide where the artifacts live.
- Single domain:
CONTEXT.md + docs/adr/ at the repo root.
- Multiple bounded contexts: a root
CONTEXT-MAP.md pointing to
src/<context>/CONTEXT.md + per-context docs/adr/.
- Record the conventions the flow assumes (a short block in
CLAUDE.md /
AGENTS.md, or a docs/agents/ note): where CONTEXT.md and ADRs live, and any
project-specific rule the base invariants don't already cover.
- Don't scaffold empty files. Note the locations; create the files when the first
term/decision actually lands (see below).
CONTEXT.md — the glossary
One entry per project-specific concept. Not a dictionary of general programming terms —
only the words that mean something particular here.
## <Canonical term>
<What it IS, in 1–2 sentences — "is", not "does". State the thing, not its behavior.>
_Avoid:_ <synonyms/near-terms that must not be used for this concept>
Rules:
- Is, not does. Define what the term is, not what it does.
- One opinionated choice. Pick the canonical word; list the synonyms to avoid so they
don't creep back.
- Project-specific only. If it's a general programming concept, it doesn't belong.
- Sharpen on contact. When a stage uses a fuzzy word, or a term two ways, resolve it
here immediately — a concrete edge-case scenario is the fastest way to force precision.
- Grow it lazily. Add a term the moment it's resolved; don't pre-populate.
docs/adr/ — decision records
Number sequentially: 0001-slug.md, 0002-slug.md.
# <NNNN>. <Decision title>
<The decision and the WHY, in 1–3 sentences.>
<!-- optional, only if they carry weight: Status · Considered options · Consequences -->
Offer an ADR sparingly — only when a decision is hard-to-reverse AND surprising AND
the result of a real trade-off. Qualifies: architectural shape, integration pattern,
technology lock-in, a boundary decision, a deliberate deviation, a rejected alternative
with subtle reasoning. Does not qualify: routine choices, anything obvious, anything a
reader would guess. An ADR for every decision is noise that buries the few that matter.
Keeping them live (every stage's job)
- 7w3 design and spec cite CONTEXT.md terms and propose ADRs as decisions land.
- Any stage that discovers a term drifting fixes it in CONTEXT.md then, not later.
- When reality diverges from an ADR, update the ADR — don't let the code quietly redefine
the decision. Same rule as the design of record: the document leads, code follows.
Source: Serge Shima (@aostrikov_agents_chat), Setup and domain model.
