// Load when reading from, writing to, or maintaining the KB. Covers layer model, structural conventions, and operational tooling.
Load into any agent that receives human direction. Use before acting on instructions, recording decisions, or producing artifacts.
Load when establishing shared vocabulary, resolving term conflicts, disambiguating domain terminology, or auditing consistency across a project's vocab. Shared vocabulary is the contract between human intent and agent action — ambiguity is the root failure mode, vocab files are the record.
Use when mining conversation history during dev work — recovering decisions from the top-level primary session, delegating bulk transcript reading to an explorer, or discovering all sessions tied to a work item across interruptions.
Use whenever you need to delegate work to another agent, run tasks in parallel, coordinate multiple agents, or inspect spawn outputs. Also use when routing work to a specific model or provider.
Load before spawning subagents to protect focus and role fit. Make sure to re-read the available agents before spawning a subagent; choose the most specific owner instead of broad defaults, then write a tight handoff with only the context that subagent needs.
Load when producing any written artifact for humans.
| name | kb-conventions |
| type | reference |
| description | Load when reading from, writing to, or maintaining the KB. Covers layer model, structural conventions, and operational tooling. |
| model-invocable | false |
Load /llm-writing if it isn't already loaded.
The KB (meridian context kb) has five layers:
Sources — raw material: articles, research, transcripts, data. Immutable. The LLM reads from sources but never modifies them.
Decisions — the reasoning layer. Why a source matters, why the wiki is shaped the way it is, what was chosen and rejected. Decisions connect sources to knowledge by explaining the interpretation and judgment applied.
Wiki — synthesized knowledge pages. How things work, concepts, architecture. The LLM owns this layer: creates pages, updates them, maintains cross-references, keeps everything consistent. Shaped by the decisions.
Log — what changed in the wiki and why. The audit trail of how the KB evolved — what was added, updated, or restructured, and what triggered it.
Schema (AGENTS.md) — user-defined governance. Defines layer structure,
conventions, and workflows.
The living KB holds the best current understanding of the system. Keep it clean, direct, and current. When a claim, explanation, structure, or term is superseded, remove it from the live KB rather than layering newer text around older understanding.
Do not preserve stale knowledge inline just because it was once true. If old
material still has value as history, move it out of the living KB into
kb/trash/ or another explicit archive area. The wiki should teach the
current system, not narrate its evolution unless the history is itself the
topic.
Current pages should read as current truth. A reader should not need to guess which paragraph still applies.
Each doc covers one coherent concept — one component, one interaction pattern, one decision. When a doc covers two unrelated topics, split it. When two docs explain the same concept from different angles, merge or cross-reference.
Name files by what they describe (token-validation.md), not when they were
written (auth-redesign-notes.md).
index.md is the entry point — a catalog with links and one-line summaries,
organized by domain. Directories emerge organically as a domain accumulates
enough distinct concepts. Nest as deep as the content warrants.
index.md
<domain>/
overview.md
<topic>.md
<sub-domain>/
<topic>.md
The overview at each level orients the reader: what exists here, how pieces relate, where to go deeper.
Load /shared-dao for vocab methodology, lifecycle, and conflict resolution.
This section covers the structural conventions.
Vocab files sit in a hierarchy matching the domain:
vocab.md) — project-wide terms used across domains<domain>/vocab.md) — terms specific to one domain<domain>/<subdomain>/vocab.md) — further scopingEach term entry includes canonical name, definition, aliases, and links.
Flag conflicts with > [!FLAG] **Needs human review** — vocab conflict: ....
Check the vocab hierarchy at each level before creating a new entry.
Link to related docs using relative paths. Cross-reference instead of re-explaining — each doc stays focused and there's one source of truth per concept. When a fact results from a decision, link to the decision record. Readers understand the system from wiki pages alone, following links to decisions when they need the reasoning.
Write docs that work in isolation:
Wiki pages teach how things work — mechanism, flows, edge cases. Capture what code can't easily tell you: component relationships, dependency directions, data flows, and why the system is shaped this way.
Use mermaid diagrams for anything spatial — component relationships, data flows, state machines. Tables for comparisons. Reference source locations rather than pasting code.
Flag content needing human attention with > [!FLAG] **Needs human review**.
Searchable with rg '\[!FLAG\]'.
Before committing: meridian kg check (broken links), meridian mermaid check
(diagram validity). meridian kg graph shows link topology.