Note 16 of 19
kaibot · operator card
Homer: the review-gated builder
You bring the job in one paragraph. It brings back branches with the receipts attached. Nothing touches main until you type the one command that does.
Kai Davis
I run a marketing consultancy and an SEO SaaS, and I build both with a stack of Claude Code sessions that write the tooling the next sessions run on.
bootstrapping.io · kaidavis.com · keywordmagic.ai · doubleyourecommerce.com
0.The shape of a run
Each card runs on its own review branch, named review/DD‑N, and ends at a verdict. Gates judge the diff against acceptance tests written when the bundle was made, plus a non-Claude reviewer and a counselors panel when you switch them on. An uncertain gate holds. A held card is harmless: you glance at the branch, you don’t clean up after it.
Violet boxes run themselves. Amber boxes need you, and there are only three.
1.Your three touchpoints
FrontThe JTBD paragraph
Say what done looks like, in your words, one plain paragraph. “A bulk memory commit is physically blocked unless a fresh 3-green receipt exists.” That sentence is the ground truth every reviewer defers to when criteria conflict or a test looks hollow. The session turns it into the bundle: PRD contracts, criteria with stable ids, and complete canonical tests. You never write those, but the paragraph is the one thing no model is allowed to write for you.
MiddleSign-offs for eyes-only criteria
A criterion with no possible automated test (“the page looks right”) ships as test: null. The queue builds everything around it, then holds the card until a sign-off file with your name lands in the bundle’s signoffs/ folder. You look at the thing, you sign, the card flips. A red test can never be signed away; the sign-off only covers what a test cannot see.
EndThe promote tap
homer-merge.sh --promote <feature> is the single command that pushes to main and closes cards. Everything before it is reversible. Staging runs autonomously and stops at a local integration branch; the irreversible step was left for a human on purpose, and that human is you.
2.The five commands
# everything runs from ~/kaibot/scripts/loops
# 1 · rehearse one card: prints the plan, builds nothing
./homer-once.sh DD-N --repo <repo> --dry-run
# 2 · one real card, deterministic gates only, you watching
./homer-once.sh DD-N --repo <repo>
# 3 · the queue: builds each card to ready|hold, never merges
./homer-linear.sh --issues DD-A,DD-B --repo <repo> --bundle <bundle> \
--model opus --reviewer-model deepseek --gate1
# add --feature <name> when cards build on each other (assembly mode)
# 4 · stage: gates the set, merges onto a local integration branch, stops
./homer-merge.sh DD-A,DD-B --repo <repo> --feature <name> --model deepseek
# 5 · promote: the only main + Linear write. Yours.
./homer-merge.sh --promote <name> --repo <repo>
# and the repair tool: re-run a built card’s canonical tests, no rebuild;
# flips a held-but-green card to ready (also how sign-offs get counted)
./homer-regate.sh --card DD-N --repo <repo> --bundle <bundle> --write-verdict3.Reading a verdict
| Verdict line says | It means | You do |
|---|---|---|
ready | Built, gated, waiting on its branch. | Nothing until stage + promote. |
GATE2-DRIFT | The reviewer found the diff drifting from the card. | Read .homer/DD‑N/round-*-findings.md. Usually a fix-slice re-runs on the same branch. |
tool_failure: gate1 | A gate tool died (panel timeout, crash). Not a code problem. | Fix or re-run the tool, then regate. The breaker freezes the queue if a gate keeps dying. |
HANG: BUILDER | The build leg produced nothing (empty diff, self-close). | Read the leg transcript; usually a re-dispatch. |
HANG: SPEC | The same criterion drifted twice; the card itself is suspect. | Read the decision brief it wrote. The spec needs your call; the queue kept moving. |
canonical-test-tampered | The repo’s copy of an acceptance test differs from the bundle’s oracle. | Someone edited the exam. Restore or investigate; never sign it away. |
ASSEMBLY-CONFLICT | Two individually-clean cards clash when stacked. | A cross-card contradiction only a human resolves. The queue stopped on purpose. |
4.What routes to homer, what stays in your hands
Homer builds functionality. You build the front end. Homer is built to spec, without taste: data, logic, pipelines, CLIs and APIs all carry real tests, so homer builds them well. What it hands back for each card is an API, its tests, and a working example of calling it, never a rendered interface. The front end has no test that can judge it, so it stays in your hands, designed by you.
Never ask homer for a front end. Ask it for the code and the API underneath one, then design the page yourself.
Acceptance tests are authored at emission time, fully formed, with real assertions. That is the corollary that keeps the system honest. A builder receives the tests as-is and is never allowed to edit them. It lands them verbatim.
On the first production run, a builder rewrote its own exams. The rewritten versions passed. When the originals were restored, they caught three real bugs. The gate now enforces this by comparing byte for byte.
5.Where things live
| Thing | Path |
|---|---|
| A card’s work | review/DD‑N branch in the runner worktree |
| Verdict + gate reports | <repo>/.homer/DD‑N/ (verdict.json, findings, gate reports) |
| The bundle | ~/kaibot/homer/bundles/<name>/ (JTBD.md, PRD.md, cards.json, tests/, signoffs/) |
| Drift ledger | per-card shards; the merge gate passes only at zero open items |
| The machinery | ~/kaibot/scripts/loops/ · mental model in the homer-loop skill |
Homer never merges to main. Cards stop at verdicts; staging stops at a local branch; the one irreversible command is yours. Written 2026‑07‑11, the day the machine started fixing the machine. ⚒
You’ve reached the end of note 16 of 19
$400 1 hour
Book a callA paid one-on-one call with answers to your questions about using AI for projects, building your AI stack, or growing your business with AI. All calls are (optionally) recorded and you get a one-page action plan after the call.