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 KIFF let the good refund through and hold the risky one for a human, before any money moves. No account, no cloud, all local.

One honest note before you start, because it decides whether this is worth your five minutes. The demo also refuses a repeat refund on an already-refunded order, and that part is table stakes: a unique constraint does it, and any competent tool implementation already does it. It is in the demo because it shows KIFF reading state, not because it is the reason to use one. The reason is KIFF Cards, the instrument that bounds what an agent does in total, which no per-call check can produce, and that is the hosted part today.

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 contract 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 KIFF 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 repeat on an already-refunded order is refused. The agent proposing the wrong thing is normal, the decision in front of it is what makes proposing it safe.

Both refusals here are the same refusal: the entity is not in a state that allows the action. That is worth having and it is not worth buying, because your database and your tool code can both do it. What neither can do is answer what the agent has done in total, because each of them only ever sees one call.

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 path routed to a human by a decision outside the agent, in five minutes, on your machine.

Understand the decision → How a decision is made: 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.