# KEEL

> KEEL is a super-thin, file-native method for human and AI-agent collaboration you drop into a git repository. v0.1.2 — 34 of 39 stories done; US-18 unsigned; E8 agent loop complete. Stdlib-Python CLI. Any model. Any harness. Agents never accept their own work.

KEEL is not another coding assistant. It is a method plus a stdlib-Python CLI that lives beside your code. Memory, contracts, laws, and proof are ordinary files. 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 model is interchangeable. The brain is not.

Start a project:

```
git clone https://github.com/monnkeebrain/keel.git my-project
cd my-project
bin/init
```

Then open the folder in the agent you already use. First message can be `boot`. If the agent edits before emitting `BOOT ok · keel v0.1.2 · <phase> · <n ready> · epics <ids or none> · <resume cue>`, stop it and re-boot.

## Site

- [KEEL one-pager (HTML)](https://keel.monkeebrain.com/): Human landing page
- [KEEL one-pager (markdown)](https://keel.monkeebrain.com/index.md): Prose mirror of the HTML page

## Method (canonical)

- [README](https://raw.githubusercontent.com/monnkeebrain/keel/main/README.md): What KEEL is, version, status, how to start a blank workspace
- [METHOD.md](https://raw.githubusercontent.com/monnkeebrain/keel/main/METHOD.md): Operating manual — the only hand-written instruction source. Adapters are generated from this file
- [PLAN.md](https://raw.githubusercontent.com/monnkeebrain/keel/main/PLAN.md): Phases, harness scope, standing metrics
- [AMENDMENTS.md](https://raw.githubusercontent.com/monnkeebrain/keel/main/AMENDMENTS.md): How `METHOD.md` may change. Additions must pay rent; removals need only a log line
- [FAILURES.md](https://raw.githubusercontent.com/monnkeebrain/keel/main/FAILURES.md): Fact-form failure log. Only logged failures may change the method
- [Source repository](https://github.com/monnkeebrain/keel): Clone, issues, template

## Guides

- [For humans](https://github.com/monnkeebrain/keel/blob/main/docs/for-humans.md): The operator path
- [For agents](https://github.com/monnkeebrain/keel/blob/main/docs/for-agents.md): The agent contract in three lines
- [Tips and tricks](https://github.com/monnkeebrain/keel/blob/main/docs/tips-and-tricks.md): Patterns from real incidents
- [System](https://github.com/monnkeebrain/keel/blob/main/docs/system.md): The tower, the layers, what an execute agent actually needs
- [Testing matrix](https://github.com/monnkeebrain/keel/blob/main/docs/testing-matrix.md): Sole in-repo provenance for harness and model pass claims
- [Epic protocol](https://github.com/monnkeebrain/keel/blob/main/docs/epic-protocol.md): E7 narrative (in force)
- [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)

## CLI

Stdlib Python only. No pip. No build. Git is the runtime. Invocation is `bin/<cmd>` (the dispatcher is `bin/keel`).

Status verbs the agent may run: `bin/claim` (ready → in_progress), `bin/review` (in_progress → review). Status `done` is forbidden.
Operator-only verbs: `bin/park`, `bin/reassign`, `bin/epic-accept`.

- [bin/init](https://github.com/monnkeebrain/keel/blob/main/bin/init): Blank project workspace; creates `src/`
- [bin/boot](https://github.com/monnkeebrain/keel/blob/main/bin/boot): Print the current BOOT line
- [bin/gate](https://github.com/monnkeebrain/keel/blob/main/bin/gate): Ready-gate a story (`bin/gate US-xx`)
- [bin/claim](https://github.com/monnkeebrain/keel/blob/main/bin/claim): Set in_progress (`bin/claim US-xx`)
- [bin/pack](https://github.com/monnkeebrain/keel/blob/main/bin/pack): Compile one story + laws + recent decisions
- [bin/review](https://github.com/monnkeebrain/keel/blob/main/bin/review): Set review after evidence (`bin/review US-xx`)
- [bin/render](https://github.com/monnkeebrain/keel/blob/main/bin/render): Generate `overview.html` for the human operator
- [bin/state](https://github.com/monnkeebrain/keel/blob/main/bin/state): Regenerate bounded `STATE.md`
- [bin/verify](https://github.com/monnkeebrain/keel/blob/main/bin/verify): Sanity-check schema, IDs, adapters, projections
- [bin/adapt](https://github.com/monnkeebrain/keel/blob/main/bin/adapt): Generate harness entry files from `METHOD.md`
- [bin/distill](https://github.com/monnkeebrain/keel/blob/main/bin/distill): Distill archive into `decisions.md`
- [bin/epic-gate](https://github.com/monnkeebrain/keel/blob/main/bin/epic-gate): Validate an epic envelope against its listed stories
- [bin/epic-claim](https://github.com/monnkeebrain/keel/blob/main/bin/epic-claim): Claim an epic (`bin/epic-claim E-n`)
- [bin/epic-pack](https://github.com/monnkeebrain/keel/blob/main/bin/epic-pack): Compile cover sheet + first unlocked story
- [bin/epic-present](https://github.com/monnkeebrain/keel/blob/main/bin/epic-present): Mark epic presented for accept
- [bin/epic-accept](https://github.com/monnkeebrain/keel/blob/main/bin/epic-accept): Batch-close a presented epic (operator only)
- [bin/park](https://github.com/monnkeebrain/keel/blob/main/bin/park): Move a story to blocked (operator only)
- [bin/reassign](https://github.com/monnkeebrain/keel/blob/main/bin/reassign): Move a story off an epic (operator only)

## Session loop

Canonical `take US-xx` — five beats:

- [P-BOOT](https://raw.githubusercontent.com/monnkeebrain/keel/main/METHOD.md): Emit `BOOT ok · keel v0.1.2 · <phase> · <n ready> · epics <ids or none> · <resume cue>` before any mutation
- [P-STORY](https://raw.githubusercontent.com/monnkeebrain/keel/main/METHOD.md): Intent → draft → `bin/gate` → human `sign US-xx`
- [P-RUN](https://raw.githubusercontent.com/monnkeebrain/keel/main/METHOD.md): `bin/claim` → `bin/pack US-xx` → execute → evidence → `bin/review`
- Human accept: `accept US-xx` — operator's speech act. The accept key never transfers by silence
- [P-END](https://raw.githubusercontent.com/monnkeebrain/keel/main/METHOD.md): `bin/state`, `bin/render`, `bin/verify`, commit, push

`take E-n` — two extra beats on top of the canonical loop:

- [P-EPIC-RUN](https://raw.githubusercontent.com/monnkeebrain/keel/blob/main/docs/epic-protocol.md): `take E-n` claims the epic and chains every unlocked story (`depends_on` is `done`). One pack per story, evidence, `bin/review`. Repeat without a new human take
- [P-EPIC-ACCEPT](https://raw.githubusercontent.com/monnkeebrain/keel/blob/main/docs/epic-protocol.md): `accept E-n` when every listed story is `review`/`done`. `bin/epic-accept` batch-closes the slice. Park and reassign are operator-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; pages are projections.
5. Raw history to `archive/`; durable lessons to `decisions.md`.
6. IDs are immutable once referenced.
7. Adapters are build artifacts; `METHOD.md` is their only source.
8. Complexity must pay rent.

## Optional

- [llms.txt specification](https://llmstxt.org/): Format this file follows