Write a standard

Choose where it lives

A standard is held in BLOM or in Git. Either way, BLOM keeps it by revision, and a revision governs work only once it's approved for Adopt.

Write one in BLOM

You need change access to the whole organization, as an Editor or an Administrator there.

1. Open Standards

   At the rail's foot, select Organization, then Standards.

2. Choose its category

   In the category it belongs to, such as Security, select Write a standard.

3. Name it

   Give its Title. Leave File name (optional) empty to make one from the title, or give your own: lower case letters, digits, dots, hyphens, and underscores, ending .md or .markdown, at most 200 characters. A name with a capital letter, such as Security-Policy.md, is refused.

4. Write its text, and save

   Write or paste the Markdown under Text (Markdown). Left empty, it starts with the title as its heading. Select Save draft r1.

The file name gives the standard its ID: harbor-security.md makes S-Std harbor-security. IDs are unique in your organization, ignoring case, so a name already in use is refused. If your organization took BLOM's Security standard, S-Std security is taken, and a second standard titled Security needs a file name of its own. A person may write more than one standard in a category.

To change a standard's text, open it and select Edit text, then Save revision. While a revision is a draft, a save keeps its number; after an approval, the next save starts the next revision. An open draft that someone else saved can be saved over only by the standard's owner or an Administrator.

What to write in it

BLOM keeps the text exactly as you save it, and reads none of it as rules: it doesn't parse a rule, its strength, or what it applies to, and it evaluates no rule. Write it for the people and agents who apply it. BLOM's default standards show one way: a Category and an Applies to line under the title, then the rules as table rows, each with an ID, a Strength, and the rule.

# Harbor security

    Category: Security

    Applies to: every change to Member onboarding

    ## Secrets

    | ID | Strength | Rule |
    | --- | --- | --- |
    | HSEC-1 | Mandatory | Secrets are never written in code, tasks, or chat. |

A Mandatory rule must be met, or covered by an exception from the standard's owner. Standards covers strength and departures.

An agent's draft, over MCP

An agent drafts with blom_draft_standard, after reading the register with blom_read_standards. It sends markdown and a requestId, with one of two shapes:

• A new standard: categoryId from the register, a title, and an optional fileName. The standard is kept at the organization, and its owner is the agent's person.
• The next revision: the standard's documentId, and editedFromPin, the pin of its latest revision from the register.

An agent writes one standard per category: where your organization already has a standard in the category, a new one is refused as category_has_standard, and the agent drafts that standard's next revision. A key limited to chosen products can't draft a standard, since a standard held in BLOM is kept at the organization. Other refusals name the problem: standard_selector_mixed or standard_selector_incomplete for the shape, document_changed for a stale pin, and draft_open_by_another for another actor's open draft.

The register shows the draft with who saved it and their person, such as Draft r1 by Codex for Ada Lovelace. A draft governs nothing, and no MCP tool approves anything.

How large it can be

• A standard held in BLOM is at most 524,288 bytes, 512 KiB, of UTF-8 text. BLOM counts bytes, not characters, so a letter outside plain ASCII counts two to four. A longer text is refused as held_file_size.
• Over MCP, a whole request is at most 256 KiB, counted in bytes, so an agent's draft must fit in that along with the rest of the request. A larger request is refused: "Request body too large: BLOM's agent channel takes at most 256 KiB."
• Through the public API or the CLI, a request may be up to 1 MiB.
• A standard held in Git may be up to 1 MiB, the largest file BLOM reads.

Keep it in Git

To keep a standard in your repository, give a Markdown file on a connected repository's Document branch an S-Std header. Document headers has the lines, and an example. Its Home line says where it's kept:

• Home: Organization: Harbor Labs, or a team, such as Home: Team: Platform, in your organization's standards source.
• Home: 1 Member onboarding (Product), in that product's repository.

The Category line must be there, but BLOM doesn't read it: the standard is listed under Category unknown, with No owner set, and nothing in BLOM sets either. Give it an ID no other document uses, BLOM's defaults included. Change it only in the repository: each commit that changes its content makes a revision, and its number moves on after each approval.

Approve it for Adopt

To put a revision in force, open the standard and read its text. Select Approve r1, write Why you approve it, and select Approve. The revision then governs work, and the next save starts r2. A standard held in Git is approved the same way.

The people who approve are listed after Approves for Adopt: the founder, to begin with. Any Administrator can approve too. An agent whose key has Admin access may approve through the public API or the CLI, as an Administrator can:

blom op standards.approveRevision --input approve.json

The file holds the standard's documentId, the revisionNumber and revisionPin it read, "decision": "granted", and a basis of 1 to 4,000 characters. BLOM records the approval as the agent's, with the person it answers to beside it. No MCP tool approves anything.

Related