From 258de2c14bb5e80846be72eae034856f2827ae1f Mon Sep 17 00:00:00 2001 From: Felix Martin Date: Thu, 4 Jun 2026 13:20:51 -0400 Subject: [PATCH] docs: make Keel the repo front door + add agent context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: lead with Keel (the human-harness), frame AntiDrift as the focus mode, keep the milestone history. Fix the "rename deferred" wording (the dir/repo is already keel; only the code identity stays antidrift) and drop the dangling 2026-05-31 spec reference (that spec was intentionally removed). - keel-architecture.md: update the rename status in the header and §8 — the directory is keel; the Go module / antidriftd binary / ANTIDRIFT_* env / ~/.antidrift -> ~/.keel migration land with the controller refactor. - add AGENTS.md (agent orientation) + CLAUDE.md symlink so claude / codex / Hermes auto-load Keel context when launched in this repo. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + README.md | 36 ++++++++++++++-------- docs/keel-architecture.md | 20 +++++++----- 4 files changed, 101 insertions(+), 21 deletions(-) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c63f39f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,65 @@ +# Keel — Agent Context + +You are working in **Keel**, Felix's human-harness. Read this, then treat +`docs/keel-architecture.md` as the source of truth for anything architectural. + +## What this is + +The inversion of an agent harness: instead of a harness watching a model work, a +model (the brain) helps observe and steer a *human*. Felix is the observed +subject; the brain is the operator. The thing we build is **the harness** — the +framework that collects Felix's real state, hands it to a swappable brain, and +acts on the reply. + +- **Brain** — swappable, rented compute: `claude` / `codex` / **Hermes** (real, + on another machine). Not the point; interchangeable behind one interface. +- **Storage** — **ActivityWatch** buckets (`keel.state`, `keel.events`). No new + DB / event store. Buckets hold *pointers*, not copies. +- **Frame** — `~/owc` (values, goals, `resources/bug-*.md` life-bugs). Reference, + never duplicate. +- **Surfaces** — a phone-friendly web UI + the WM status bar (`~/.antidrift_status`). +- **Effectors** — gated writes (Marvin tasks, capture, AntiDrift enforce; later + Beeminder datapoints, `~/owc` notes). Start propose-and-confirm; trend toward + autonomy. The gate is per-effector config — Felix's agency-vs-cage dial. + +## What runs today + +**AntiDrift**, Keel's first *mode*: a Go focus daemon (ports-and-adapters) — +`evidence.Source` (perception) · `tasks.Provider` (Marvin) · `knowledge.Source` +(the `~/owc`-derived profile) · `ai.Backend` (the brain) · `enforce.Guard` +(window-minimize). The cockpit work is **loosening its session controller** into a +general *collect → brain → act* loop where a focus-session is one mode among many. + +```bash +go run ./cmd/antidriftd # local web UI at http://localhost:7777 +go test ./... +``` + +## Naming / rename status + +The directory and git repo are **`keel`**. The **code identity is intentionally +still `antidrift`** — Go module `antidrift`, `antidriftd` binary, `~/.antidrift/` +runtime, `ANTIDRIFT_*` env. The code rename lands later, *with a state migration* +(`~/.antidrift/` owns the live ledger), during the controller refactor. Don't +`mv ~/.antidrift` or rename the module casually. + +## How to work here + +- **Reuse before building.** Read the code before claiming something is missing. + AntiDrift already is the harness skeleton; widen it, don't rebuild. +- **Reference, don't duplicate.** `~/owc` and each tool's store stay source of + truth; Keel never becomes a hidden second source. +- **Ship visible proof.** Every session ends with a real artifact — reframing and + planning are not progress. Felix's named failure mode is tooling-as-avoidance; + resist it. +- **Concise coaching.** The status line is one signal / one action / one question. + Not "nice summaries" — that was explicitly rejected. +- **Local-first; mind secrets.** The operator runs as the full Unix user with no + sandbox; window titles and on-disk keys can leak. Filter at the assembler. + +## Pointers + +- `docs/keel-architecture.md` — authoritative architecture (components, data flow, + AW-as-storage, the open questions in §8). +- `docs/superpowers/` — AntiDrift focus-mode feature specs/plans (historical). +- `README.md` — project front door. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/README.md b/README.md index 13fdf15..9b6753c 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,26 @@ -# AntiDrift +# Keel -A personal focus operating system: treat each work session as an explicit -commitment (next action, success condition, timebox), and make drift visible. +A **human-harness** that helps Felix hold course toward his higher goals: it +collects his real state from the tools he already uses, hands it to a swappable +brain (`claude` / `codex` / Hermes), and acts on the reply through gated +effectors — surfaced on a web UI and the WM status bar. The brain, the storage +(ActivityWatch), and the data sources are reused; the harness is what we build. -> **This repo is the seed of [Keel](docs/keel-architecture.md)** — a human-harness -> that helps Felix hold course toward his higher goals. AntiDrift's focus harness -> becomes Keel's first *mode*; the broader architecture (collectors, AW-as-memory, -> swappable brain, web UI, gated effectors) is in `docs/keel-architecture.md`. The -> repo/code rename is deferred until the controller-refactor decision. +> **Architecture:** [`docs/keel-architecture.md`](docs/keel-architecture.md) is the +> source of truth. **Agents:** read [`AGENTS.md`](AGENTS.md) first. -See `docs/superpowers/specs/` for the focus-OS design; `docs/keel-architecture.md` -for where it's headed. +## Focus mode (AntiDrift) + +What runs in this repo *today* is **AntiDrift**, Keel's first mode: a personal +focus operating system that treats each work session as an explicit commitment +(next action, success condition, timebox) and makes drift visible. Keel +generalizes its controller so a focus-session becomes one mode among several +(house, body, review, capture). The milestone history below is this mode's record. + +> **Naming:** the directory and git repo are renamed to `keel`; the *code identity* +> is intentionally still `antidrift` (Go module, `antidriftd` binary, `~/.antidrift/` +> runtime, `ANTIDRIFT_*` env). The code rename lands with a state migration during +> the controller refactor — see `docs/keel-architecture.md` §8. ## Run @@ -82,6 +92,6 @@ works. M1 (evidence & audit): active-window tracking, two-tier evidence store (disposable per-session raw log + permanent hash-chained session summaries), -and live SSE updates. Live drift judgment and the ambient nudge arrive in later -milestones (see the roadmap in -`docs/superpowers/specs/2026-05-31-go-focus-os-design.md`). +and live SSE updates. Live drift judgment and the ambient nudge arrived in later +milestones (M3 and M3.5 above; the original roadmap spec has since been removed — +code and git history are the record). diff --git a/docs/keel-architecture.md b/docs/keel-architecture.md index a2030d6..290c2a7 100644 --- a/docs/keel-architecture.md +++ b/docs/keel-architecture.md @@ -18,12 +18,14 @@ status: authoritative > **Name & home.** *Keel* is the system: a human-harness that helps Felix hold > course toward his higher goals. The name answers AntiDrift's metaphor — *drift* > is what a vessel does with nothing to hold it; the *keel* resists drift and -> keeps you on an even keel (steady mind). **This repo (`antidrift`) is Keel's -> seed**: AntiDrift's focus harness becomes Keel's first *mode*. The code/repo -> rename is **deferred** until the controller-refactor decision (§8); for now -> only this design doc lives here as the authoritative home. Moved from -> `~/dev/higher/` on 2026-06-04 — that directory was the scaffold where the -> decision to extend AntiDrift was made, and now retires. +> keeps you on an even keel (steady mind). **This repo is now `keel`** — AntiDrift's +> focus harness becomes Keel's first *mode*. The directory and git repo are +> renamed; the **code identity is intentionally still `antidrift`** (Go module +> `antidrift`, binary `antidriftd`, runtime `~/.antidrift/`, `ANTIDRIFT_*` env). +> That *code* rename is **deferred** until the controller refactor (§8) because +> `~/.antidrift/` owns the live ledger/state and needs a migration, not a `mv`. +> Moved from `~/dev/higher/` on 2026-06-04 — that directory was the scaffold where +> the decision to extend AntiDrift was made, and now retires. --- @@ -245,8 +247,10 @@ behavioral story) or left out initially. `~/owc/stream.md` vs `~/wrk/pkb/stream.md` vs dead inboxes) and rewiring `blurt` to append there. - **Controller refactor shape** — how invasive the AntiDrift generalization is; do - we branch the daemon or grow it in place. **This is also the trigger for the - repo/code rename to `keel`.** + we branch the daemon or grow it in place. **This is also when the *code* rename + lands** — Go module / `antidriftd` binary / `ANTIDRIFT_*` env and + `~/.antidrift/` → `~/.keel/` with a state migration. (The directory is already + `keel`; only the code identity still says `antidrift`.) - **Cross-device AW** — sync work-laptop AW or not (see §7). - **Secret hygiene** — an increasingly autonomous operator runs as the full Unix user; plaintext keys exist on disk; the privacy boundary in ③ must be real.