Epheme Port
Tutorial

Build it, rule by rule.

This is what your agent does under the hood: it drafts, specifies, links, stages, and verifies — you review and approve. Follow a real app, BafGo Kitchen, from one rule to verified. No accounts, no server, no API key. The repo is the source of truth.

Your agent runs

rule new · specify · claim · link · stage · request-review · verify

You run

approve — or click approve in bafgo serve

Prefer to run it yourself? Every command below works by hand too — the agent is faster, never required. Pointing an agent at this instead? Use the agent guide.

One-time setup · you, once

$ npm config set @bafgo:registry https://npm.bafgo.com/ once
$ npm install -g @bafgo/cli bafgo --version
$ git clone https://github.com/bafgo/bafgo.git cd bafgo
$ bafgo init in your repo
01

Draft the rule

rule

Start in plain language, then shape it into a checkable spec. Every rule keeps a note on why it exists, so a reviewer can see the reasoning.

your agent runs this
$ bafgo rule new R-123 --title "Timer keeps running while the screen sleeps" --when "a timer is active,the display sleeps" --then "the countdown continues,the chime still fires" --source "product decision"
→ .bafgo/rules/R-123.yaml created (draft)
title: Timer keeps running while the screen sleeps
track: executable
when:
  - a timer is active
  - the display sleeps
then:
  - the countdown continues
  - the chime still fires at zero
grounding:
  source: product decision
  rationale: timers must stay trustworthy
draftspecifiedimplementedreviewapprovedverified
02

Specify when → then

rule

A rule is simple: every when must hold, every then must pass. If you need an "or", split it into two rules.

your agent runs this
$ bafgo rule specify R-123
→ R-123 specified
draftspecifiedimplementedreviewapprovedverified
03

Implement + link

code + tests

The code and tests get written, by a developer or an AI assistant, then linked to the rule. The port records the links. The work can come from anyone.

your agent runs this
$ bafgo claim CH-42 --rule R-123
$ bafgo link R-123 --code public_site/site/index.html --unit test/timer-core.test.js
✓ links recorded
draftspecifiedimplementedreviewapprovedverified
04

Review the demo

review

You review a live demo. Approval is a real step in the flow, not a comment that gets buried in a ticket.

your agent runs this
$ bafgo stage CH-42 --demo https://preview.epheme.org/r-123
$ bafgo request-review CH-42
you run this — or click approve in bafgo serve
$ bafgo approve CH-42 --by dana
✓ approved by dana · 2m ago
draftspecifiedimplementedreviewapprovedverified
05

Verify

verified

The tests written from the same rule go green. The rule is now verified end to end.

your agent (or CI) runs this
$ bafgo verify CH-42
→ CH-42 verified · 2 tests green
draftspecifiedimplementedreviewapprovedverified
06

When it's a judgment call

exploratory

Some decisions aren't testable. "Dark mode feels right at night" isn't a when → then, so it takes the exploratory track: a person judges the demo instead of a generated test.

No tests are generated. The rule is approved, not verified. The board says so.
drafthuman reviewapproved
07

A real board

overview

This is what the repo's .bafgo/ produces: real rules, real files, real tests.

R-124Adding a duplicate item is a no-opverified
R-125Clearing checked items keeps only the uncheckedverified
R-126Durations parse from "45 sec" · "1:30" · "2 hr"verified
R-127Repeating a step inserts a rest between repsverified
R-123Timer keeps running while the screen sleepsimplemented
R-128Dark mode feels right at nightdraft
08

Lock the record

tamper-evident

Under the board is a record that can't be quietly rewritten. The event log is hash-chained, every file is fingerprinted, and approvals can be signed with a key.

your agent keeps the record
$ bafgo chain
→ chained 14 events
$ bafgo manifest
→ manifest written · root 0f3a… · 6 rules · 14 events
you run this once (keygen), then approve
$ bafgo keygen --name dana
→ private key written · add the public key to .bafgo/keys.yaml
$ bafgo approve R-123 --by dana
→ approved · signed by dana

Replay the check any time: bafgo manifest --verify confirms the root, the chain, and the signatures all still hold.