diff --git a/CLAUDE.md b/CLAUDE.md index c4b9d90..080bcd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -319,4 +319,4 @@ Default vocabulary — `needs-triage`, `needs-info`, `ready-for-agent`, `ready-f ### Domain docs -Single-context: [`CONTEXT.md`](./CONTEXT.md) (the ubiquitous-language glossary — use its terms, not the synonyms it avoids) + `docs/adr/` at the repo root. See `docs/agents/domain.md`. +Single-context: [`GLOSSARY.md`](./GLOSSARY.md) (the ubiquitous-language glossary — use its terms, not the synonyms it avoids) + `docs/adr/` at the repo root. See `docs/agents/domain.md`. diff --git a/CONTEXT.md b/GLOSSARY.md similarity index 100% rename from CONTEXT.md rename to GLOSSARY.md diff --git a/docs/agents/domain.md b/docs/agents/domain.md index b548c53..ed8a370 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -4,8 +4,8 @@ How the engineering skills should consume this repo's domain documentation when ## Before exploring, read these -- **`CONTEXT.md`** at the repo root, or -- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic. +- **`GLOSSARY.md`** at the repo root, or +- **`GLOSSARY-MAP.md`** at the repo root if it exists — it points at one `GLOSSARY.md` per context. Read each one relevant to the topic. - **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. @@ -16,31 +16,31 @@ Single-context repo (most repos): ``` / -├── CONTEXT.md +├── GLOSSARY.md ├── docs/adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/ ``` -Multi-context repo (presence of `CONTEXT-MAP.md` at the root): +Multi-context repo (presence of `GLOSSARY-MAP.md` at the root): ``` / -├── CONTEXT-MAP.md +├── GLOSSARY-MAP.md ├── docs/adr/ ← system-wide decisions └── src/ ├── ordering/ - │ ├── CONTEXT.md + │ ├── GLOSSARY.md │ └── docs/adr/ ← context-specific decisions └── billing/ - ├── CONTEXT.md + ├── GLOSSARY.md └── docs/adr/ ``` ## Use the glossary's vocabulary -When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids. If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 82cfbf5..bf595e2 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,6 +1,6 @@ # Issue tracker: GitHub -Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations. +Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations. ## Conventions