oxFlow Wiki

ADR-0004 — Every knowledge-base doc carries YAML frontmatter

2 min read

Context

The team’s pre-merge docs used a plain-markdown convention: bold-key metadata directly below the h1.

# Research — database analysis
 
**Date:** 2026-04-17
**Author:** Bilal Jawadi (@bilaljawadi45)
**Status:** draft

That reads nicely on github.com but does not parse. The wiki viewer (Quartz v4, 0002-wiki-stack-is-quartz-v4) expects YAML frontmatter for titles, dates, tags, backlinks by slug, and index queries. Without structured metadata, we cannot build the birds-eye “progress” page or filter by status/type.

Decision

Adopt YAML frontmatter on every markdown file under docs/, decisions/, research/, meetings/, status/, prompts/, raw-dumps/, and templates/. Schema: meta/frontmatter-schema.md.

Required on every file: title, type, tags, bmad_source. Required on dated files (research, meetings, status, decisions, raw-dumps): date, author, status.

Migration: meta/scripts/migrate-frontmatter.py parses the existing **Key:** value blocks into YAML and is idempotent. Run once. Re-run with --check as a CI guard.

Alternatives considered

  • Keep bold-key metadata — rejected; doesn’t parse, no machine readability, doesn’t feed index pages.
  • TOML frontmatter — rejected; less universal, most MD tooling (Quartz, Obsidian, GitHub’s Jekyll renderer) speaks YAML first.
  • JSON sidecar files — rejected; splits metadata from content, bad DX for humans.

Consequences

Positive

  • Queryable by the wiki: type, status, tags, date all surface in navigation.
  • GitHub’s rendered markdown still displays YAML frontmatter as a plain code block — no visual regression.
  • Agents have a clear contract: “copy the template, fill in the fields.”

Negative

  • 109 files migrated in one commit; git blame for the body line-count shifts by 8–10 lines on those files. git log --follow still works.
  • Templates now have placeholder YAML (date: "YYYY-MM-DD", status: draft | in-review | final) that new doc authors must replace — slightly harder to copy-paste wrong.

Follow-up

  • Phase 2: wire meta/scripts/migrate-frontmatter.py --check into CI on PRs that touch *.md.
  • Phase 2: Quartz theme surfaces status, date, author, tags on every page header.

References

Graph View

Backlinks