KEEL is a super-thin method for human and AI-agent collaboration you drop into a git repository:
signed stories, standing laws, a live snapshot, and a CLI any agent can run.
Deterministic commands in bin/ — not prompts that drift.
Any agent. Any harness. bin/claim then bin/review; the accept key stays human.
The human surface
bin/render writes overview.html from the same files the agent reads.
data/stories.json, data/epics/, decisions.md, laws/, and STATE.md — one canonical store.
Checkboxes, quoted evidence, glanceable counts. No JavaScript framework.
The operator judges here — not in the chat.
phase: P4 — workshop skill in testing · generated 2026-08-31 14:04Z · HEAD 322184e · generated by bin/render
nothing waiting on human judgment ✓
| backlog | ready | in progress | review | blocked | done |
|---|---|---|---|---|---|
| 1 | 0 | 0 | 0 | 0 | 34 |
idle
US-39 accepted. E8 agent loop complete. US-18 unsigned.
bin/review · no worktree-add (done, US-38..39)data/stories.json, data/epics/, decisions.md, and laws/ — same truth the agent boots from.Same repo. Two audiences.
A real Hermès session. BOOT, then evidence. AC-3 fails — and the agent stops. That halt is the product. KEEL outputting FAIL means the rules held. Source: screenshots/keel-proof-hermes.png · US-38 evidence bundle.
bin/, will not take US-39, will not piggyback. FAIL is a win — every dev gets a gate that actually holds.01 The problem
You brief an agent. It writes code. The thread dies, the model changes, the tool gets deprecated — and the context that made the work coherent is gone. Next session starts from zero, or from whatever that vendor still holds.
02 What KEEL is
KEEL is not another coding assistant. It is a thin method you drop into a git repository: standing laws, signed stories, a live snapshot, and a CLI any agent can run. Open a new chat in any harness. The agent boots from the files, does one piece of work, and stops for you to accept. Swap Claude for Grok, Codex for Open WebUI — the project does not move.
Two guides
You write and sign the contracts, judge overview.html, and say accept. The quality of the user story is the quality of the result.
Three lines: git pull --ff-only, read STATE.md, emit bin/boot. Then route the task. Never invent work. Never self-accept.
03 Why teams use it
Built for people already working with AI agents — founders, staff engineers, studios — who need the work to survive a model change, a new laptop, or a new hire.
KEEL does not care if you run Claude Code, Codex, Hermès, Open WebUI, Amp, Grok, or Factory Droid. The method lives in files those tools already know how to read.
Status, decisions, and "where we left off" sit in the repo. A fresh chat with zero history can boot, report the state, and continue. No vendor lock-in for context.
Agents may draft and verify. They may not mark work done. Park, reassign, and epic-accept are operator-only. The agent does not run git worktree add. The gate held on every model we tested — including when nobody reminded the agent.
Intent becomes a contract with acceptance criteria before code moves. Unverifiable requests get parked. Optional scope.touch / scope.forbid and depends_on bind the pack to its ground.
A "done" claim without a commit hash or an artifact path is void. You review quoted evidence on a generated page, not a vibe from the chat.
Stdlib Python. No pip. No build. Git is the runtime. Clone, run bin/init, open the repo in the agent you already use. Local-only is first-class.
04 How a session runs
You open the repo in whatever agent you use today. The agent must prove it read the project before it may edit. Then: one signed task, evidence, your accept. Tomorrow a different model can pick up the same files.
Open the repo in your agent. It reads the live snapshot and the law slices for the task, then must print a BOOT line before it may touch a file.
BOOT ok · keel v0.1.2 · …
Turn a request into a signed story with acceptance criteria. If it cannot be verified, it is parked — not shipped.
bin/gate US-xx · sign US-xx
The agent gets one story, the project rules, and recent decisions. It works inside that scope, cites evidence per AC, then hands the story back through bin/review. Done is forbidden for the agent.
claim · pack · review
You review the evidence on overview.html and say the literal word. The accept key never transfers by silence, enthusiasm, or elapsed time.
accept US-xx
Snapshot updates. Decisions are written down. Failures are logged as facts. bin/verify green, then commit and push — or it did not happen.
bin/state · bin/verify
04a For a slice larger than one story
An epic is a dispatch envelope: id E-n, goal, ordered stories, depends_on epics, scope.touch / scope.forbid. take E-n claims the whole slice. The agent chains unlocked stories, no human turn between them, presents the epic when the frontier stops, and waits. You judge once.
Each story depends_on is done. One pack, evidence, bin/review. Next unlocked story, repeat — no new take.
bin/claim E-n · bin/pack · …
When every listed story is review or done, say the word. bin/epic-accept batch-closes the slice. Park and reassign are operator-only.
accept E-n
05 Inside the repo
Not a database. Not a cloud workspace. Ordinary files your editor, git, and
any agent can read. The method sits beside your code in src/.
The only hand-written instruction source. Adapters are compiled from it.
Source of truthStack, design, and domain constraints. Versioned. New versions append.
VersionedNarrative, AC[], DoD[], status, optional scope and depends_on. Editable until ready. Locked at launch.
Goal, ordered stories, depends_on epics, scope. One file per epic. The dispatch unit larger than one story.
Rationale and consequences, newest first. Corrections supersede; they do not rewrite.
Append-onlyPhase, open intents, active epics, resume cue. O(current), never O(history). Regenerated freely by bin/state.
Checkboxes, quoted evidence, glanceable first. Generated by bin/render. Groups stories by epic. Works from file://.
Context packs, evidence bundles, raw logs. Write-once. Distill later into decisions.md.
Everything outside src/ is method. bin/init creates the blank for a new ship.
init · boot · gate · claim · pack · review · state · render · adapt · verify · distill · epic-gate · epic-claim · epic-pack · epic-present · epic-accept · park · reassign. Dispatcher: bin/keel. No pip. No build. Stdlib Python.
06 Rules that do not move
These are the load-bearing laws of a KEEL repo. They change rarely, and only with written rationale. Everything else in the method can be simplified.
STATE.md stays bounded: O(current), never O(history).data/, laws/, decisions.md). Pages and views are projections.archive/. Durable lessons distilled into decisions.md.METHOD.md is their only source.The model is interchangeable. The brain is not.
Claude today, Grok tomorrow, a local model on a flight. KEEL does not bind you to a vendor. Local-only is first-class. When you need sync, git push and pull is enough.
07 Provenance
Same test, many tools: cold start, remote repo, full loop. Fresh chat, zero history. The agent states project status, continues from the resume cue, and stops for a human accept. Verified — not assumed. Sole in-repo source for harness and model pass claims: docs/testing-matrix.md.
Cold start · with remote · full loop
Same gates, every family
The agent proves it read the repo before it edits anything. Matches bin/boot output verbatim.
If nothing is ready, it reports and waits. It does not improvise a backlog. Held 3/3 in the matrix.
Every "done" names a commit hash or an artifact path. No citation, no done. The reporting law.
The agent stops at PENDING and waits for a human word. It never accepts itself. Park, reassign, epic-accept: operator-only.
Read next
These live in the upstream repo. The site links out; nothing is fork‑left to drift.
You write and sign the contracts. You judge overview.html. You say accept.
The agent contract in three lines. METHOD.md wins if this disagrees.
Sole in-repo source for harness and model pass claims. The arms, the gates that held.
FieldMicro‑contracts, agent shells have no TTY, demand the BOOT line. Patterns from real incidents.
ArchitectureKEEL as a system. The tower, the layers, what an execute agent actually needs.
E7 in forceTake an epic, chain unlocked stories, present, judge. The narrative behind bin/epic-*.
Why KEEL does not own worktrees. bin/review is the in_progress → review verb.
The elicitation protocol as a loadable skill. Ask once, gate, sign.
08 Start
Clone, run bin/init. That empties the method's contracts
and creates src/ for your code. Open the folder in the
agent you already use. Prefer a click? Use this template on GitHub — or unzip and init.
# blank workspace
git clone https://github.com/monnkeebrain/keel.git my-project
cd my-project
bin/init
git add -A && git commit -m "init workspace"
# canonical `take US-xx` (or `take E-n` for an epic slice) python3 bin/claim US-xx python3 bin/pack US-xx --save # … execute inside the write-set, evidence per AC … python3 bin/review US-xx python3 bin/state && python3 bin/render && python3 bin/verify
bin/init creates the local repo.git inspection runs with --no-pager. Stack law, not choice.epic-accept, and git worktree add: not yours to run.