From 6b745aaad1dfe3d8e4769725493f98881ad0f549 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Mon, 7 Sep 2026 13:56:55 +0200 Subject: [PATCH] AGENTS.md: document experimental/unstable stability policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ollie is experimental and unstable; optimize for a clean minimal codebase over preserving behavior. No backward-compatibility shims, deprecation aliases, or legacy fallbacks — change things fully and delete the old form. Standing preference, applied without asking, so agent behavior doesn't need per-task course correction. --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a759c6a..0491b4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,6 +91,15 @@ For direct Go testing, use the packages covered by `make test-core` and `make te - Go: `gofmt`, short variable names, error returns (no panics), table-driven tests. - Tool scripts: emit structured output (`STATUS=ok`, `STATUS=error`). Image/LSP tools return JSON content blocks. - Prompts: markdown, concise, example-driven. Follow the pattern in existing `tools-*.md` files. +## Stability & compatibility +Ollie is **experimental and unstable** software. The features and API are approaching stability but are not there yet. Optimize for a clean, minimal codebase over preserving existing behavior. + +- **Do not add backward-compatibility code.** No shims, deprecation aliases, legacy fallbacks, dual-format parsers, or "keep the old path working" branches. When something changes, change it fully and delete the old form. +- **Prefer subtraction.** Removing code is a feature. If a rename, refactor, or new design lets you delete the old thing, delete it — don't leave both. +- **Break callers freely.** Renaming a field, changing a wire format, or altering a `ctl` verb is fine; update all call sites in the same change. There are no external consumers to protect. +- **Extreme minimalism.** No pointless indirection, no defensive code for cases that can't happen, no configuration knobs "just in case." + +This is a standing preference, not a per-task instruction. Apply it without asking. ## Architecture (key concepts) 1. **One integration surface**: `olliesrv` exposes sessions and agents through a 9P2000 filesystem. Frontends include `o`, `ollie-9p`, KDE, Kate, Emacs, and scripts. Reads from `chat`, `statewait`, `eventwait`, and `feed` provide blocking/event-driven synchronization. 2. **Session and tool processes**: Each session owns an agent runtime in `olliesrv` and a separate `toolsrv` process. They communicate over an authenticated Unix socket using 9P. `toolclient` can respawn local toolsrv processes and can deploy/start toolsrv remotely over SSH with socket forwarding.