| 1 | # CONTEXT.md Format |
| 2 | |
| 3 | ## Structure |
| 4 | |
| 5 | ```md |
| 6 | # {Context Name} |
| 7 | |
| 8 | {One or two sentence description of what this context is and why it exists.} |
| 9 | |
| 10 | ## Language |
| 11 | |
| 12 | **Order**: |
| 13 | {A concise description of the term} |
| 14 | _Avoid_: Purchase, transaction |
| 15 | |
| 16 | **Invoice**: |
| 17 | A request for payment sent to a customer after delivery. |
| 18 | _Avoid_: Bill, payment request |
| 19 | |
| 20 | **Customer**: |
| 21 | A person or organization that places orders. |
| 22 | _Avoid_: Client, buyer, account |
| 23 | |
| 24 | ## Relationships |
| 25 | |
| 26 | - An **Order** produces one or more **Invoices** |
| 27 | - An **Invoice** belongs to exactly one **Customer** |
| 28 | |
| 29 | ## Example dialogue |
| 30 | |
| 31 | > **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?" |
| 32 | > **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed." |
| 33 | |
| 34 | ## Flagged ambiguities |
| 35 | |
| 36 | - "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts. |
| 37 | ``` |
| 38 | |
| 39 | ## Rules |
| 40 | |
| 41 | - **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid. |
| 42 | - **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution. |
| 43 | - **Keep definitions tight.** One sentence max. Define what it IS, not what it does. |
| 44 | - **Show relationships.** Use bold term names and express cardinality where obvious. |
| 45 | - **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. |
| 46 | - **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine. |
| 47 | - **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts. |
| 48 | |
| 49 | ## Single vs multi-context repos |
| 50 | |
| 51 | **Single context (most repos):** One `CONTEXT.md` at the repo root. |
| 52 | |
| 53 | **Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other: |
| 54 | |
| 55 | ```md |
| 56 | # Context Map |
| 57 | |
| 58 | ## Contexts |
| 59 | |
| 60 | - [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders |
| 61 | - [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments |
| 62 | - [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping |
| 63 | |
| 64 | ## Relationships |
| 65 | |
| 66 | - **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking |
| 67 | - **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices |
| 68 | - **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money` |
| 69 | ``` |
| 70 | |
| 71 | The skill infers which structure applies: |
| 72 | |
| 73 | - If `CONTEXT-MAP.md` exists, read it to find contexts |
| 74 | - If only a root `CONTEXT.md` exists, single context |
| 75 | - If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved |
| 76 | |
| 77 | When multiple contexts exist, infer which one the current topic relates to. If unclear, ask. |
| 78 |