IZ4, step by step.

1. Install the CLI

One line to copy and paste. The format is open and the CLI is free. The installer fetches the single iz4 file published for your system, checks its checksum, proves it runs and puts it on your PATH: no runtime, no Git, no admin rights. Where no file fits your system, it installs from source instead, with Git as the only prerequisite.

curl -fsSL https://raw.githubusercontent.com/nige123/cli.iz4.you/main/install | sh

irm https://raw.githubusercontent.com/nige123/cli.iz4.you/main/install.ps1 | iex

git clone https://github.com/nige123/cli.iz4.you iz4
ln -s "$PWD/iz4/bin/iz4" ~/.local/bin/iz4     # needs Rakudo; or: cd iz4 && zef install .

Keep it current with iz4 update: it brings any install, file or source, to the newest release, and iz4 update check only says whether there is one.

Then, in your repository, iz4 init. It asks what the software is for and who it is for, writes the file, and offers to find a first invariant. Or write it by hand: copy this into a file called IZ4 at the root of your repo and answer the questions. Put the domain your project answers for in the first line, and give each promise its whole name: a few lower-case words joined by hyphens, then your domain. Then iz4 foundation restore writes in the foundation every IZ4 carries, word for word.

IZ4 your-domain.com

IS FOR WHAT?  What is this software for, in a sentence?
IS FOR WHO?   Who is it for?

PROMISE first-promise.your-domain.com

  WHEN      The situation it applies in.
  ALWAYS    What must remain true there, whatever is rebuilt.
  PROTECTS  Whose what must not be defeated.

  CHANGES REQUIRE no approval; current promise still applies
  CHECKED WITH    linked tests; failures warn, never block

Reading an invariant

An invariant is an expression that includes a promise, how it is checked, and what a change to it requires; an IZ4 writes each one as a card. The promise is the first three fields. One for payments:

PROMISE charged-once.shop.example.com

  WHEN      a customer pays for an order
  ALWAYS    the customer is charged once, never twice
  PROTECTS  the customer's money

  CHANGES REQUIRE signed human approval for the exact change
  CHECKED WITH    linked tests; failures block commit

• WHEN · the situation it applies in.
• ALWAYS · what must remain true there. In a list, every item holds.
• PROTECTS · the people, or what of theirs, it is there for.
• CHANGES REQUIRE · what it takes to change its promise: nothing while the invariant is exploring, a person's signed yes once it is established.
• CHECKED WITH · how it is checked: tests that name it, which warn while it is exploring and stop a commit once it is established.

The foundation reads the same way. The first of its five:

FOUNDATION humans-first.iz4.you

  WHEN      anyone is affected by the system, by its use, or by work on it
  ALWAYS
    - help people thrive, on their own terms
    - respect every person's dignity: no goal, instruction or greater good makes anyone disposable
  PROTECTS  each person's dignity, and their own say over how they thrive

  CHANGES REQUIRE verified foundation release only
  CHECKED WITH
    - exact canonical match required
    - linked tests; failures block commit

You need no code to read one, or to write one. An IZ4 is not a specification: it keeps what people intend true while the software around it changes. Passing checks are evidence about the checks that ran, not proof that the software is correct.

2. Find your invariants

iz4 add asks three questions, one at a time: where does this apply, what must remain true there, and what does that protect. When, always, protects. All three bind together: WHEN scopes, ALWAYS binds, and PROTECTS decides what counts as keeping it. None narrows or excuses another.

It also tells you when something is not an invariant. The golden test: if the whole system were rewritten tomorrow, would the people rebuilding it regret not knowing this? "Uses PostgreSQL" fails it. "Private data is permanently deleted when an account is deleted" passes.

With an agent to hand, iz4 suggest proposes a few candidates for you to review. iz4 invariants prints the foundation beside your own, each by name. The human decides what must survive. The tool only asks.

3. Lock them in

Commit the file beside the README. iz4 check ticks what it can verify and says what it cannot. Then hand the invariants to every coding agent before it touches the code:

iz4 agent install          # a managed section in AGENTS.md
iz4 review install         # an advisory pre-push review against the invariants

Every IZ4 carries the foundation, such as human-agency.iz4.you, and nothing written beside them can weaken them. Your invariants sit inside that lock.

A new invariant is exploring: its promise can change without a yes, and a failing test only warns. iz4 establish NAME when the promise is agreed. From then on a change waits for your signed yes, and a failing test stops the commit. The foundation holds either way.

The gate

iz4 init installs the gate as your commit hook. A commit that changes a promise stops and asks a person, there and then. An agent can suggest a change. Only a person can agree.

• pass · no promise changed.
• agreement-required · an established invariant's promise reworded or lowered, or the invariant withdrawn; what it is for changed; a test that names an invariant removed, or rewritten to check something else; the IZ4 file itself removed. A person says yes. Comments and layout pass.
• blocked · no yes lifts it: a failing test that names an established invariant, an altered foundation, a reused name.
• unassessed · a check could not run, so nothing is claimed.

iz4 approve shows each change in the invariant's own words, one at a time, and signs your yes for that exact change. Change a file afterwards and it asks again.

Does it hold? The CLI carries an offline benchmark: 22 scripted agent changes to a small job platform, 17 of them breaking an invariant. Enforced, the gate held 16. It missed a new route around the invariant that no test covers, and it asked a yes it did not need to when a test was made stricter. It measures the boundary, not a model: whether a model keeps an IZ4 it was shown takes live runs. The results.

The hook on your machine is a convenience. The boundary an agent cannot switch off is the same gate run in CI as a required check.

4. Share in the register

Create a workspace, add your project, and the Connect CI page gives you one command to paste in your repo, which adds this workflow and your token. It reports counts, outcomes and coverage on every push. A private repo's file and code stay in CI. We never access them. From a connected checkout, iz4 register and iz4 report do the same from the command line.

# .github/workflows/iz4.yml
name: iz4
on: [push]
jobs:
  report:
    runs-on: ubuntu-latest
    continue-on-error: true   # advisory: never blocks a release
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 1 }
      - run: |
          curl -fsSL https://iz4.you/iz4-report -o iz4-report
          chmod +x iz4-report
          ./iz4-report --url https://iz4.you/api/v1/projects/YOUR_ID/reports --token "$IZ4_TOKEN" \
              --release "$GITHUB_REF_NAME" --run-id "$GITHUB_RUN_ID"
        env:
          IZ4_TOKEN: ${{ secrets.IZ4_TOKEN }}

Connect CI fills in your project's address and stores the token for you.

Publish, then show your badge

Preview what goes public and publish. Your project page then mints your IZ4 badge, the QR code inside the diamond, for your site and packaging. For your README, drop in the status badge:

[![IZ4](https://iz4.you/p/YOUR_ID/badge.svg)](https://iz4.you/p/YOUR_ID)

From a connected checkout, iz4 badge prints these lines with your own id filled in, offline.

The status badge is live. It shows the card's evidence-backed state, a failed check included. Never a score.

Your card keeps itself current

• Your CI reports on every push, so the card's evidence follows your code without anyone remembering to update it.
• The README badge is an image served by the register. When the evidence changes, the badge changes. There is nothing to paste again.
• You choose which revision the card presents. A report adds evidence but never changes what the card presents. When you release, set the new revision.
• If reports stop for 30 days, the card marks the evidence stale. That says how old the evidence is. It does not judge the project.

5. Pass it on

Software is built on software. Your card counts how many of the projects you depend on declare an IZ4 of their own, and names the ones that do not. Ask them. Every project that answers makes the next request easier, and the ground firmer for everyone standing on it.

Copy this, change the name, and send it wherever that project prefers. The register never contacts anyone on your behalf.

Hello. We depend on this project and would find an IZ4 file useful.

An IZ4 is one plain text file beside your code saying what the software
is for, who it is for, and the few things that must remain true for it
to keep serving them. It helps anyone reading the code, and it helps AI
agents follow your intent rather than guess it. Every IZ4 begins with
the same commitment: the software is for humans first.

There is an open tool and format at https://iz4.you/start, and nothing
needs to be registered or paid for. If it is useful to you, we would be
glad to see one.

Thank you for the work you already do.

Add an IZ4 to a library you maintain and every project standing on it gains a declared dependency the moment its CI next reports.

Register your IZ4 Pricing