The HI/1 format

A hi/*.md file is markdown a person would have typed anyway. Nothing below the frontmatter exists to serve the tool, and nothing the tool writes should look machine-generated.

---
hi: 1
families: [SEND, RECEIPT, SPEND]
owner: leif
---

# Chat

## Intent

I want to talk to people I trust without anyone in the middle being able to
read it, and without it feeling like a security product. It should feel like
texting.

## Criteria

- **SEND-1**  I hit enter and the message shows up right away, marked as sending.
  - **SEND-1.a**  If I have no connection it queues and tells me.
  - **SEND-1.b**  If the thread was deleted before it sends, it warns me first.
- **SEND-2**  It reaches them and the mark changes to sent.

- **RECEIPT-1**  I can tell sent from read without thinking about it.

- **SPEND-1**  An operator can cap what the service spends in a day.

## Retired

- **SEND-3**  My messages auto-delete after 24 hours.
  retired: we decided this was a different product

Four rules

1. A criterion is one markdown list item: a bold id, two spaces, and a sentence. However long the sentence runs it stays on one line, so criteria stay greppable and diffable.
2. You write the id yourself, because you are the one who has to say it out loud. SEND-1 is a name, not a position.
3. Letters are cases, numbers are steps, alternating strictly. Reading an id tells you what kind of thing it is.
4. Ids are permanent and append-first. hi never renumbers anything, refuses an id that is already taken, and keeps a retired id reserved.

Why a list item, and not a bare line

This is the format's one correction, and it is worth knowing about. Criteria used to be written as bare SEND-1 sentence lines. They looked fine in the source, and every test passed, because every test asserted on what the parser read back.

Markdown joins consecutive plain lines into a single paragraph. So on GitHub, in any preview and on any docs site, the file rendered as one wall of run-together sentences. That falsified the first thing the format promises: that a hi file reads as an ordinary document with no tool installed. Making each criterion a list item fixed it, and cases indent two spaces per level so the tree renders as a nested list too.

The sections

• ## Intent is human prose. What this feature is for and what it should feel like. This is the thing a spec can never carry, and the first thing an agent should read.
• ## Criteria holds the lines.
• ## Retired holds criteria you changed your mind about, keeping their ids spoken for. It is also where a reader learns the most: an agent handed hi/ alone, with no code and no help, got the product right, and the retirements were what taught it the rules.

What a sentence may carry

Inline markdown works: `code`, **bold**, *italic* and [links](url). Anything that looks like markup is escaped before it is interpreted, never executed. A fenced code block inside your intent prose is prose: the parser reads nothing structural between fences, so you can show an example of the format inside your own file.

A criterion is a plain sentence

No prefix, no fields, no slot in front of the sentence. For four releases hi required every criterion to open with As a <role>, and read that role back with a four-word heuristic. It is gone. It changed no behavior, it cost every line four words in front of the only part anyone reads, and parsing English prose to recover it was exactly the thing the format had refused elsewhere.

If a criterion needs to say who it speaks for, it says so in English, the way any sentence does. An operator can cap what the service spends in a day names its subject and reads as writing. Files written under the old rule still parse and render unchanged; those criteria are simply sentences that begin with As a.

The test that rule was carrying survives as advice. Try putting As a ___, in front of your sentence. If you cannot finish it, you wrote a fact about the system rather than something somebody wants. That costs nothing, because it happens in your head while you type.

Hand editing

The parser is looser than the writer. It accepts a bare line with no bullet, no emphasis around the id, and indented continuation lines, so a file you edited by hand is never rejected. Your file's own byte shape, its line ending, its trailing newline, its frontmatter style, is carried through a write rather than normalized, and hi never reflows prose it did not write.

Next

Ids covers the grammar and why permanence matters more than it sounds.