| name | shared-language |
| description | Use when the task mentions domain language, CONTEXT.md, terminology, shared vocabulary, or when the same concepts are being explained repeatedly in different sessions. Builds and maintains a shared language document. |
Shared Language
Build and maintain .opencode/CONTEXT.md — a glossary of project-specific
terms, each defined in ONE sentence. It is a glossary and nothing else: no
design docs, no ADRs, no examples. If an entry grows beyond one sentence, move
it to a design doc and keep a one-sentence pointer here. Every conversation
that re-explains the same concept wastes tokens; the glossary replaces those
explanations with a single reference.
When to Create or Update
- You find yourself explaining the same concept (>2 sentences) across
multiple messages or sessions.
- You encounter a term the user uses that has project-specific meaning.
- After a design discussion — capture the decisions as shared language
entries.
Format
.opencode/CONTEXT.md uses this exact format:
# Shared Language
- `<term>`: <one-sentence definition>
- `<term>`: <one-sentence definition>
Each entry is one line. No paragraphs, no examples, no "further reading".
How Agents Use It
Before reasoning about the codebase, scan .opencode/CONTEXT.md:
- If a term appears, use its one-sentence definition directly — do not
re-explain or expand.
- If a concept is missing but you needed 3+ sentences to convey it, add an
entry after the session.
Each definition replaces 5-20 sentences of repeated explanation, so the agent
spends fewer tokens re-deriving concepts.
ADR triage
Offer an ADR only when a decision is ALL of: hard-to-reverse, surprising (a
reader would not guess it), and a real trade-off (both options cost something).
Otherwise a .opencode/CONTEXT.md entry suffices — do not spawn an ADR.
Maintenance
- Keep entries to one sentence; an overgrown entry belongs in a design doc.
- Delete entries that no longer apply (removed features, renamed concepts).
- Sort alphabetically.
