All guides
Get started
The BLOM method
Agents
Developers
Administration
DocsThe BLOM method
Document headers
The lines at the top of a Markdown file that make it a BLOM document, what each one holds, and what BLOM records when one is off.
Where the header is
BLOM reads headers from the Markdown files, ending .md or .markdown, on a connected repository's Document branch, outside its Excluded paths. A file's header is every line above its first heading of level 2 or deeper, such as ## Requirements. A # title doesn't end it.
Each header line reads Key: value, with a plain key in any case. BLOM skips bold keys such as **ID:**, table rows, quoted or indented lines, code blocks, and HTML comments. YAML front matter isn't read as YAML: its lines count as ordinary lines, so quoted values and keys with underscores aren't understood.
The lines BLOM reads
| Line | Required for | What it holds |
|---|---|---|
ID | Every type | The type, a space, and a name, such as P-Spec 1-2. |
Home | Every type | Where the document belongs. |
Owner | Every type | Who answers for it, kept as written, never matched to a person. |
Revision | Every type | The revision it says it is, such as r3. |
Governed by | Every type | The standards it was written against, kept as text. |
Parent | P-Spec | The P-Spec of the nearest item above with one, or none. |
Category | S-Std | The standard's category, which BLOM doesn't read. |
Status, Kind | ADR | The decision's status, such as Proposed, and its kind. |
An ID's type is written exactly as BLOM names it: P-Spec, D-Spec, T-Spec, DB-Spec, S-Std, ADR, V-Plan, or R-Plan. Without a valid ID line, a file isn't a document, and BLOM reads nothing else in it. A placeholder in angle brackets, such as ID: P-Spec <number>, makes the file a template, which BLOM skips.
An ID is unique in your organization, ignoring case, whatever its type and wherever the document is held. When two files claim one ID, or a file claims the ID of a document BLOM already holds, the files are refused as duplicate_id, and none gets a revision. If your organization took BLOM's Security standard, S-Std security is taken.
Home and Parent
Home is a path from the product, each step a number and a name, with the level in parentheses if you like: 1 Member onboarding > 1-2 Invitations (Capability). BLOM places the document at the item whose number ends the path, in the repository's product, and checks the rest of the path against its items. A Home that matches no item leaves the document unplaced.
A standard is homed at a product, never below one: 1 Member onboarding (Product), or the product's name alone. In your organization's standards source, its Home may instead read Organization: Harbor Labs or Team: Platform, named as BLOM shows them. An ADR may also name its product alone.
Plans. Teams are part of Standard, Premium, and Enterprise. Every plan is free for now; see Pricing.
A P-Spec's Parent is the P-Spec of the nearest item above its home that has one, or none.
Moved files and changed IDs
A file you move or rename keeps its document while its ID stays the same. To change an ID, move the file in the same commit, keep its type, and add a ## Previous IDs table naming the old ID, the path BLOM last read it at, and that read's commit, by at least its first seven characters:
## Previous IDs
| ID | Path | Commit |
| --- | --- | --- |
| P-Spec 1-2-invites | specs/invites.md | 4e1a9c2 |documents.listGit gives each document's path and commit. Changing an ID in place makes a new document, and the old one reads as absent, its revisions kept.
Revisions and the Revision line
Each commit on the Document branch that changes a document's content records one revision, pinned to that commit. BLOM reads no document history from before the connection's first read.
BLOM numbers revisions itself: the first is r1, and the number moves on only after a revision with that number is approved. Until then, each change records a new pin under the same number. BLOM approves no spec, ADR, or plan revision, so theirs stay r1; a standard read from Git moves to r2 once its r1 is approved for Adopt.
The Revision line holds a whole number, with or without an r: Revision: r3 or Revision: 3. BLOM reads the number it starts with and ignores the rest, so 2.1 reads as 2. A line that starts otherwise, such as v2.3, gets malformed_header_line:revision, and BLOM keeps nothing of it. Where the number differs from BLOM's, BLOM records revision_number_differs and keeps its own.
Record parts
BLOM compares content, not every byte. It leaves out the record parts, so editing only them keeps the revision you have:
- the header lines
ID,Home,Parent,Revision,Status,Superseded by, andGoverning; - the sections headed
Approvals,Revision history,Corrections, andPrevious IDs, at any level, each up to the next heading at its level or above.
Everything else is content, the title and the Owner, Category, Kind, and Governed by lines among it, so editing Governed by makes a new revision.
Findings
When a header is off, BLOM records a finding with the read, and still records the revision unless the ID is a duplicate or the file can't be read. The app doesn't show findings: documents.listGit, through the public API or blom op in the CLI, lists each document a connection read, with its path, commit, revision, pin, and findings.
| Finding | What it means, and the fix |
|---|---|
missing_header_line:line | A required line is missing, such as owner. Add it. |
malformed_header_line:revision | The Revision line doesn't start with a number. Write r3 or 3. |
duplicate_header_line:line | A line appears twice; BLOM kept the first. Delete the other. |
home_not_matched:Home | The Home is missing, or its last step matches no item, so the document is unplaced. End it with the item's number and name. |
home_differs:Home | The last step matched, but the other steps, names, or levels differ from BLOM's. Write them as BLOM shows them. |
home_level_mismatch:Home | A document other than a standard names the organization or a team, or a standard sits below its product. Home it where its type belongs. |
parent_not_ancestor:Parent | The Parent is missing, or isn't a P-Spec homed above this one. Name the nearest one above, or none. |
parent_skips:ID | A nearer P-Spec, the one named, sits between. Make it the Parent. |
duplicate_id:paths | Another file or document has this ID, so no revision is recorded. Give each its own. |
revision_number_differs:source n, BLOM m | The Revision line's number isn't BLOM's. Write BLOM's. |
too_large | The file is over 1 MiB, and BLOM doesn't keep it. Split it. |
not_utf8 | The file isn't UTF-8 text. Save it as UTF-8. |
size_limit | The file has more than 20,000 lines or a line over 65,536 characters, or two ID lines. Shorten it, or drop the extra ID line. |
BLOM records the last three only where the file held a document; a new file it can't read is skipped without one.
Limits
BLOM reads a Markdown file of up to 1 MiB, 20,000 lines, and 65,536 characters a line. It can't read a Document branch holding more than 1,000 Markdown files outside its Excluded paths: the connection shows ! Temporarily failing until enough are excluded. See Connect a repository.
An example for each type
P-Spec
# Invitations
ID: P-Spec 1-2
Home: 1 Member onboarding > 1-2 Invitations (Capability)
Parent: P-Spec 1
Owner: Ada Lovelace
Revision: r1
Governed by: S-Std specification r1D-Spec
# Invitation screens
ID: D-Spec 1-2
Home: 1 Member onboarding > 1-2 Invitations (Capability)
Owner: Grace Hopper
Revision: r1
Governed by: S-Std specification r1T-Spec
# Invitation expiry
ID: T-Spec 1-2-invite-expiry
Home: 1 Member onboarding > 1-2 Invitations (Capability)
Owner: Grace Hopper
Revision: r1
Governed by: S-Std specification r1DB-Spec
# Invitation data
ID: DB-Spec 1-2
Home: 1 Member onboarding > 1-2 Invitations (Capability)
Owner: Grace Hopper
Revision: r1
Governed by: S-Std specification r1S-Std, in the standards source
# Harbor security
ID: S-Std harbor-security
Home: Organization: Harbor Labs
Owner: Grace Hopper
Revision: r1
Category: Security
Governed by: S-Std specification r1ADR
# Invitations are kept in one table
ID: ADR invitations-store
Home: Member onboarding
Owner: Grace Hopper
Revision: r1
Status: Proposed
Kind: Deciding
Governed by: S-Std adr r1V-Plan
# Expiry checks
ID: V-Plan 1-2-invite-expiry
Home: 1 Member onboarding > 1-2 Invitations (Capability)
Owner: Ada Lovelace
Revision: r1
Governed by: S-Std specification r1, S-Std testing r1R-Plan
# Expiry release
ID: R-Plan 1-2-invite-expiry
Home: 1 Member onboarding > 1-2 Invitations (Capability)
Owner: Ada Lovelace
Revision: r1
Governed by: S-Std specification r1Related
Write to us, and we'll answer and add it here.