# KEEL

> A super-thin, file-native method for human and AI-agent collaboration. v0.1.2 · 34 of 39 stories done · US-18 unsigned. Cycle ships one pack at a time; the accept key stays human.

KEEL is a method plus a stdlib-Python CLI that lives beside your code. Memory, contracts, laws, and proof are ordinary files in a git repository. Open Claude Code, Codex, Hermes, Open WebUI, Amp, Grok Build, Factory Droid, or whatever you use next week. The agent boots from the files. You keep the accept key.

The drift problem the method answers: chat threads die, models change, vendors deprecate tools — and the context that kept the work coherent is gone. KEEL puts that context in the repo. A fresh chat with zero history boots, reports state, and continues.

## Quick start

```bash
git clone https://github.com/monnkeebrain/keel.git my-project
cd my-project
bin/init
git add -A && git commit -m "init workspace"
```

`bin/init` empties this repo's dogfood (stories, decisions, ledgers, archive) and creates `src/` for your code. Everything outside `src/` is method.

Then open the folder in the agent you already use. First message can be `boot`. If the agent edits before emitting a BOOT line, stop it and re-boot.

## Why teams use it

- **Any agent, any model.** The method lives in files those tools already read. KEEL ships stdlib Python only — no pip, no build, no platform to adopt.
- **The project is the memory.** Status, decisions, and "where we left off" sit in the repo. A fresh chat with zero history can boot, report, continue. No vendor lock-in for context.
- **Humans keep the accept key.** 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`.
- **Work comes as signed stories.** Intent becomes a contract with acceptance criteria before code moves. Unverifiable requests get parked, not shipped.
- **Evidence, or it did not happen.** A "done" claim without a commit hash or an artifact path is void. You judge on quoted evidence in `overview.html`, not a vibe from the chat.
- **Story-per-file epics or stay-stories.** `bin/take E-n` claims an epic and chains unlocked stories; each story still has its own accept. `bin/claim` and `bin/review` are the only agent status verbs; `done` is forbidden.

## How a session runs

1. **P-BOOT** — agent reads `STATE.md`, the law slices for the task, and the target story. It must print `BOOT ok · keel v0.1.2 · <phase> · <n ready> · epics <ids or none> · <resume cue>` before it may touch a file.
2. **P-STORY** — intent becomes a gated story (`bin/gate US-xx`), then the operator says `sign US-xx`. The agent may not self-sign.
3. **P-RUN** — `bin/claim US-xx` → `bin/pack US-xx` → execute inside the write-set (default `src/`, `archive/evidence/`, `archive/packs/`) → evidence per AC → `bin/review US-xx`. Then stop.
4. **Human accept** — operator says `accept US-xx` or `reject`. The accept key never transfers by silence, enthusiasm, or elapsed time.
5. **P-END** — `bin/state`, `bin/render`, `bin/verify`, commit, push. Unpushed state is not truth.

### Or, take an epic (E-n) — two extra beats

For a slice larger than one story:

- **P-EPIC-RUN** — `take E-n` claims the epic and chains every unlocked story (each `depends_on` is `done`). One pack, evidence, `bin/review` — repeat without a new human take.
- **P-EPIC-ACCEPT** — when every listed story is `review`/`done`, the operator says `accept E-n` and `bin/epic-accept E-n` batch-closes the slice. Park and reassign are operator-only.

The agent never parks, never reassigns, never `epic-accept`s, never creates a git worktree.

## Inside the repo

| Path | Role |
|---|---|
| `METHOD.md` | Operating manual — only hand-written instruction source. Adapters are compiled from it |
| `laws/*.md` | Standing constraints: stack, design, domain. Versioned |
| `data/stories.json` | Signed intents (narrative, AC[], DoD[], status). Optional `scope.touch` / `scope.forbid` and `depends_on[]` |
| `data/epics/E-n.json` | Epic envelopes: goal, ordered stories, `depends_on` epics, scope |
| `decisions.md` | Append-only residue (D-nn), newest first. Corrections via supersede |
| `STATE.md` | Bounded snapshot (regenerated). `O(current)`, never `O(history)` |
| `overview.html` | Human decision surface (`bin/render`). Generated. Works from `file://` |
| `archive/` | Packs and evidence, write-once |
| `src/` | Your project's code |
| `bin/` | CLI dispatcher plus wrappers |

### CLI

The dispatcher is `bin/keel`. Thin wrappers: `init · boot · gate · claim · pack · review · state · render · adapt · verify · distill · epic-gate · epic-claim · epic-pack · epic-present · epic-accept · park · reassign`. Stdlib Python only.

## Invariants

1. Everything that matters lives in this repo, never only in a harness.
2. `STATE.md` stays bounded: `O(current)`, never `O(history)`.
3. No done without evidence mapped to AC / DoD.
4. One canonical store (`data/`, `laws/`, `decisions.md`). Pages and views are projections.
5. Raw history to `archive/`. Durable lessons distilled into `decisions.md`.
6. IDs — story ids, law keys — are immutable once referenced.
7. Adapters are build artifacts. `METHOD.md` is their only source.
8. Complexity must pay rent.

## Provenance

The same test across 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.

**Harnesses that passed.** Open WebUI + Open Terminal · Hermes · OpenCode · Codex · Claude Code · Amp Code · Grok Build · Factory Droid.

**Models that passed.** Grok 4.6 · Claude Opus · Claude Fable · GPT-5.5 · GPT-5.6 · Qwen3.8-27B · Kimi 3 · Ox Alpha / GLM 5.3 Flash · Qwen 3.8.

**Gates that held under every arm.** BOOT line before any mutation · no invented work · evidence citation · acceptance authority stays with the human.

Sole in-repo provenance source: [`docs/testing-matrix.md`](https://github.com/monnkeebrain/keel/blob/main/docs/testing-matrix.md).

## Guides

- [For humans](https://github.com/monnkeebrain/keel/blob/main/docs/for-humans.md) — the operator path. Quality of stories is the quality of the product.
- [For agents](https://github.com/monnkeebrain/keel/blob/main/docs/for-agents.md) — the agent contract in three lines. METHOD wins if this disagrees.
- [Tips & tricks](https://github.com/monnkeebrain/keel/blob/main/docs/tips-and-tricks.md) — patterns from real incidents. BOOT demand, micro-contracts, ZIP path.
- [System](https://github.com/monnkeebrain/keel/blob/main/docs/system.md) — KEEL as a system. The tower, what an execute agent actually needs.
- [Epic protocol](https://github.com/monnkeebrain/keel/blob/main/docs/epic-protocol.md) — E7 narrative. `take E-n`, present, accept.
- [Agent loop (E8)](https://github.com/monnkeebrain/keel/blob/main/docs/e8-isolation.md) — why KEEL does not own worktrees.
- [Story-workshop skill](https://github.com/monnkeebrain/keel/blob/main/skills/story-workshop/SKILL.md) — elicitation as a loadable skill (P4).

Canonical method: [github.com/monnkeebrain/keel](https://github.com/monnkeebrain/keel). Agent map: [llms.txt](https://keel.monkeebrain.com/llms.txt). HTML twin: [keel.monkeebrain.com](https://keel.monkeebrain.com/).