Quickstart

There is no init step. hi finds your repository, makes the file it needs, and writes the sentence you gave it.

Install

brew install corvidlabs/tap/hi
# or, from crates.io (the crate is human-intent, the command is hi):
cargo install human-intent

Prebuilt binaries for macOS (both architectures), Linux and Windows are on the release page.

Write something down

Run this inside any repository. The family is the part before the number, and it picks the file: SEND-1 lands in hi/send.md, which hi creates if it is not there.

hi SEND-1 "I hit enter and the message shows up right away, marked as sending."
# hi/send.md  +SEND-1

Hang a case off it. Letters are cases, so SEND-1.a lands directly under its parent:

hi SEND-1.a "If I have no connection it queues and tells me, and never silently disappears."
hi SPEND-1 "An operator can cap what the service spends in a day."

Say what it is for

Open hi/send.md and write the ## Intent block. hi left a question there as a comment; replace it with a couple of sentences about what this feature is for and what it should feel like. Keep a paragraph on one line however long it runs, and use a blank line where you want a break.

## 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.

This is the part a spec can never carry, and the first thing an agent should read. Do the same in INTENT.md at the root for the product as a whole. Until you do, hi export reports no intent and hi check keeps saying so on its note line: hi will not pass its own question off as something you wrote.

Read it back

hi ls
# hi/send.md
#   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, and never silently disappears.
# hi/spend.md
#   SPEND-1  An operator can cap what the service spends in a day.

hi check
# 3 criteria · 2 families · 2 files
# note: INTENT.md has no product-level why yet

That note never fails and never changes the exit code. hi created INTENT.md on your first capture and will keep mentioning it until there is prose in it, because the product-level why is the one thing a spec can never carry.

Look at the page

hi view
# intent.html  written

One self-contained file: a sticky feature rail, search with match highlighting, sort, keyboard navigation, and a copyable link for every id. It fetches nothing, so you can attach it to an email and it will open on a plane. With scripting off every criterion is still there, and the controls stay hidden rather than offering a search box that cannot search.

The page is named after the # heading of your INTENT.md, which is the one place you actually named your product.

Change your mind

Do not delete the line. Retiring keeps the id spoken for forever, and keeps the reason next to the thing it explains:

hi retire SPEND-1 "we decided this was a different product"

Next

The HI/1 format explains what hi just wrote into that file, and Ids explains why SEND-1.a is spelled the way it is.