Skip to content

Metrognome Vault

This is the Obsidian vault for the Metrognome codebase. It is shared knowledge between Aaron and AI agents — every dev is an agent, every page is for both. Whole-tree grep is the navigation primitive; READMEs are hubs.

Authority

Source-of-truth chain (highest authority overrides lower):

  1. Business logic (business/) — immutable rules about how the product works. Code conforms. Code drift is a bug; doc drift is escalation.
  2. Specs (features/<name>/spec.md) — canonical design intent for an implementation. Bridges business to code. Updated when intent changes.
  3. Code — the running thing. Subordinate to spec, which is subordinate to business logic.

Audience priority (broader subsumes narrower):

  • Agent docs — the entire vault. Agents read everything.
  • Staff docs — business/ + ops/ published as docs.metrognome.com via sites/staff/.
  • Public docs — help/ published as help.metrognome.com via sites/public/.

Layout

Subtree Purpose Authority Published
business/ Immutable product rules Highest (overrides specs and code) Staff site
ops/ Staff procedures and how-tos Procedures only Staff site
features/ Design intent + plans + ralph artifacts per feature (folder per feature) spec.md overrides code —
decisions/ ADRs (append-only history) Reference —
engineering/ Codebase knowledge: architecture, domains, infrastructure, agent tooling Reflects code —
marketing/ Brand, ICP, positioning, KPIs, ad strategy Reference —
help/ Customer-facing reference — Public site
general/ Company-level context: thesis, pillars, people, business model, real estate, strategy, vendor stack Reference (canonical for entity/people/footprint facts) —
documenting/ Meta — how to write/update vault pages (per-area conventions + audit checklist) Reference —
/sites/ (repo root) mkdocs publish wrappers — outside docs/ because mkdocs forbids site_dir inside docs_dir — —

Conventions

  • Every subtree has a README.md (or index.md where it doubles as a mkdocs landing) that indexes its contents.
  • Every subtree maintains a log.md for dated edits — separate cadence per area.
  • Specs are first-class permanent docs. Each feature is a folder under features/ containing spec.md (canonical intent), plan.md (ralph plan), prompt.md (ralph protocol), plus ad-hoc artifacts (research, runbook, retro). They stay after shipping and are updated as intent changes.
  • mkdocs sites are projections over vault subsets via explicit nav: in /sites/<site>/mkdocs.yml.
  • All .md files are tracked (!docs/**/*.md in .gitignore).