oxFlow Wiki

oxFlow authoring contract

5 min read

If you are an AI assistant working in this repo (Claude Code, Cursor, anything else), read this file first. It is the authoring contract. Follow it or your PR will bounce.

This repo is the single source of truth for both planning decisions and implementation progress on oxFlow. See ADR-0001 for how it was assembled.

Orient yourself

The team

See TEAM.md for the canonical mapping. Some handles are opaque (candymachineater is Ibrahim Ahmed), so never refer to people by handle alone.

Attribution format — every mention of a person uses the full form:

Real Name (@handle)

Example: Ibrahim Houissa (@ibrahim-h361). Never bare @ibrahim-h361.

In dense lists where the full form repeats, @handle alone is fine after the full form has appeared earlier in the same file.

Where does what go

You are writing…TemplateGoes attype:
Daily to-do listtemplates/daily-log.mdstatus/daily/YYYY-MM-DD.mddaily
Meeting notestemplates/meeting-note.mdmeetings/YYYY-MM-DD-<slug>.mdmeeting
Research writeuptemplates/research-note.mdresearch/YYYY-MM-DD-<slug>.mdresearch
Architecture / scope decisiontemplates/decision-adr.mddecisions/NNNN-<slug>.md (4-digit, never reused)adr
Formal entity spec(match neighbouring files)docs/entities/<layer>/<slug>.md or docs/foundation/<slug>.mdspec
Companion note on a BMAD-synced doctemplates/research-note.mdresearch/YYYY-MM-DD-<slug>.md that links to the docs/bmad/... file via wikilinkresearch

One doc per file. A meeting that produced a decision gets both a meeting note and an ADR; the meeting note links to the ADR.

Frontmatter checklist by type

Every markdown file under docs/, decisions/, research/, meetings/, status/, prompts/, raw-dumps/, templates/, plus index.md, progress.md, and this file — must have valid YAML frontmatter.

Fielddailymeetingresearchadrspecbmadtemplate
title: (quoted string)✅✅✅✅✅✅✅
date: (ISO, unquoted in real files)✅✅✅✅——quoted placeholder
author: (Real Name (@handle))✅✅✅✅——placeholder
status:✅✅✅✅——placeholder
type:✅✅✅✅✅✅✅
tags: (list, 2–3 preferred)✅✅✅✅✅✅✅
bmad_source:nullnullnullnullnullshanull
attendees:—✅—————
deciders:———✅———
supersedes:———optional———

Additional free-form keys (e.g. prompted_by, time, source) are allowed — they render in the page metadata panel.

The five hard rules

  1. One doc = one PR. Never push directly to main. Branch, PR, review, merge.
  2. Frontmatter title is the only title. Do not write a # Title h1 at the top of the body — Quartz uses the frontmatter title: as the page header. A body h1 creates a visible duplicate.
  3. Wikilinks first. Prefer [[slug]] or [[slug|display text]]. Fall back to relative markdown links only when you need a specific heading ([anchor](./path.md#heading)) or a non-markdown target ([prototype](./prototypes/oxflow-ui/pages/estimate-editor.html)).
  4. docs/bmad/ is read-only. Owned by the sync script. Companion notes go in research/ (not a separate folder) and link inward via wikilink.
  5. Tag every doc. tags: [] is a sign you didn’t think about it. Aim for 2–3 tags — folder-topic (e.g. database, oxcon, handover) and phase (e.g. phase-1, phase-2). Skip only when genuinely ambiguous.

Status + date rules

Allowed status: values:

draft | in-progress | proposed | accepted | superseded | done

Nothing else. No free-form qualifiers like draft — pending review — use status: draft and put the qualifier inside the body or as a related: note.

Date format:

  • ISO YYYY-MM-DD, unquoted in real files: date: 2026-04-21
  • Templates use quoted placeholder "YYYY-MM-DD" — you MUST replace it with the real unquoted date on copy
  • Filename date must match frontmatter date. If the filename is 2026-04-17-...md, frontmatter date: must be 2026-04-17. The linter enforces this.

ADR filenames use NNNN-<slug>.md — four-digit zero-padded number, never reused. The date lives in the frontmatter only.

Linking cheat sheet

# Wikilinks — preferred; resolves by slug regardless of folder
[[business-rules]]
[[item|Item spec]]            # custom display text
 
# Relative markdown — for headings or non-markdown targets
[Item §lifecycle](./docs/entities/1-work-hierarchy/item.md#lifecycle-states)
[Estimate prototype](./prototypes/oxflow-ui/pages/estimate-editor.html)
 
# Business-rule IDs — auto-linked in Quartz (just type them)
This follows BR-019 and BR-023a.
 
# External
[Claude Managed Agents](https://docs.claude.com/...)

Full cheat sheet: templates/README.md.

Before you PR

Run the linter locally:

python3 meta/scripts/lint-wiki.py --check

Exits 0 if clean. Otherwise prints every violation with file:line. Fix before pushing.

House style

Any standalone HTML deliverable (rendered research, dashboards, one-off reports) uses the tokens, typography, and named components in BRANDING.md. Do not pull in Tailwind, Bootstrap, shadcn for one-offs — the token block is the framework.

Prefer diagrams over prose when a diagram aids comprehension. Named components (.mini-table, .layer-stack, .pipeline, .card-row) cover most cases. For custom shapes, use inline SVG styled with the same tokens.

The upstream visual source is proposal/index.html and presentation/index.html; BRANDING.md lifts from these — do not re-derive.

What you MUST NOT do

  • Do not push directly to main.
  • Do not write a body # Title h1 when the frontmatter has title:.
  • Do not use bare @handle — use Real Name (@handle) (after the first full use, @handle alone is OK in dense lists).
  • Do not invent new status: or type: values outside the schema.
  • Do not hand-edit anything under docs/bmad/. The sync script will overwrite you.
  • Do not rename a file without updating every link to it. Wikilinks by slug survive; relative paths do not.
  • Do not delete someone else’s daily log, meeting note, or research file, even if it looks incomplete.
  • Do not invent colours or fonts in standalone HTML — use BRANDING.md.
  • Do not create new top-level folders without an ADR.

Graph View

Backlinks