Ship one governed action in 5 minutes

Pick the action you’d never let an agent take unsupervised — a refund — and ship a governed version of it. You scaffold a runnable refund domain, run it, and watch the boundary let the good refund through, hold the risky one for a human, and refuse the duplicate — before any money moves. No account, no cloud, all local.

This is the fast path: install → scaffold → run → read the decisions. KIFF is an MIT Go framework; this quickstart runs entirely on your machine. KIFF Cloud is the hosted way to run the same boundary later — optional, not required here.

1. Install and scaffold

go install github.com/kiff/kiff/cmd/kiff@latest
kiff new -scenario refund github.com/acme/refunds
cd refunds
go mod tidy
make demo

kiff new -scenario refund generates a runnable refund domain: an Order entity, a MARK_PAID action, an approval-gated REFUND_ORDER action, a headless HTTP API, and a demo script. make demo runs it end to end.

Building against a local checkout of the framework? Add -replace-local /path/to/kiff. Want a smaller starter without the refund scenario? kiff new github.com/acme/thing.

2. The useful action runs

make demo marks an order paid, then has the agent propose a refund on it. The refund is a real, consequential action — and it runs:

order-2  PAID
  agent → REFUND_ORDER  $12.00
  KIFF  ✓ ALLOWED — the contract is satisfied → your executor refunds → REFUNDED

This is the point of KIFF: the agent does the work you’d otherwise keep it away from, because the boundary checked the action against the order’s state and your policy first. KIFF returns the decision; your code executes the refund on allowed.

3. The risky path waits; the repeat is refused

The same domain makes the dangerous cases safe without you writing defensive glue:

  agent → REFUND_ORDER  $999.00, high-risk
  KIFF  ⏸ HELD — approval required   (the executor did NOT run)
      human → approves
  KIFF  ✓ ALLOWED — refund executes → REFUNDED

  agent → REFUND_ORDER  (same order, retried)
  KIFF  ✗ BLOCKED — order is already REFUNDED   (refused before money moves again)

A high-risk refund holds for a human; a duplicate refund on an already-refunded order is refused. The agent proposing the wrong thing is normal — the boundary is what makes proposing it safe.

4. It replays, and it’s on the record

Every decision and execution is protocol data, not an optional log. The entity’s state rebuilds from the stored events alone:

  replay from events → REFUNDED
      materialized == replayed

That replay — plus the recorded decisions and approvals — is the proof of what happened and why. You can verify it yourself; it isn’t a number on someone’s dashboard.

What you just shipped, and what’s next

You put an agent on a refund and let it run, with the risky and duplicate paths handled by a boundary outside the agent — in five minutes, on your machine.

Understand the boundary → How the boundary works: events, state, typed decisions, approvals, and the no-self-approval rule.
Already have an agent? Connect an existing agent: attach the guard in observe mode, watch what it does, derive a starter domain from real traffic, then enforce — no rewrite.
Run it hosted → Govern one action over HTTP: route a consequential action through KIFF Cloud over plain HTTP, no Go required.
Go deeper → Reusable operational domains is the thing you build once and connect any agent to.

The framework and every scaffold live in the public MIT repo, kiff/kiff. docs.kiff.dev owns the guided journey; the repo owns the code.