xonecas.io
79113
Ma

mini-coding-agent / commit 8ec6a30

chore: more docs work

xonecas2026-10-05 8ec6a305d9bc1a5a2845561deb97e8953e17b056 parent 79078d2

2 files changed

AGENTS.md+0−108
@@ -6,100 +6,6 @@ This file holds intent, direction, and guardrails — not a description of the
66 code. The source is the source of truth for behavior. If a fact can be learned
77 by reading the code, it does not belong here; keep this file short.
88
9-## Intent
10-
11-- A small, auditable core with no hidden machinery.
12-- A minimal system prompt with no injected meta-guidance.
13-- Provider work implemented in-tree over a small set of wire protocols.
14-- Durable, user-owned, readable session logs.
15-- An append-only TUI with a bounded live region and no full-screen buffer.
16-- Local models (Ollama / llama.cpp / vLLM) and hosted models treated as equals.
17-- One `zig build` produces one static binary. No runtime, no interpreter, no
18- Node, no `node_modules`, no post-install scripts, no supply chain beyond what
19- the code needs.
20-
21-## Direction
22-
23-Deferred, not rejected. Do not build unless explicitly promoted:
24-
25-- context compaction / summarization / masking;
26-- reading or resuming sessions (the JSONL log is write-only today);
27-- prompt templates; custom agents / subagents / delegation;
28-- an extension or plugin system; a settings TUI; overlay editors;
29-- OAuth and any custom auth flow (environment keys and stored credentials only);
30-- MCP, image generation, multi-agent orchestration;
31-- sandboxing, approval prompts, permission policies;
32-- tests and CI (standing rule: no tests unless asked);
33-- macOS/Windows support and cross-platform abstractions. Target Linux first.
34-
35-## Guardrails
36-
37-Hard constraints. Do not cross these without explicit direction:
38-
39-- **Zig only.** One `zig build` produces one binary. No Node, Bun, Deno, npm, or
40- any JS/TS step. A C dependency is allowed only when explicitly approved.
41-- **No TUI library or framework.** Render with direct ANSI writes to stdout:
42- append-only scrollback plus a bounded live region. No alternate screen, no
43- full-screen cell grid.
44-- **The provider layer is in-tree.** Implement the wire protocols directly —
45- `openai-completions`, `openai-responses`, `anthropic-messages`,
46- `google-generative-ai`. Never depend on an external provider library.
47-- **Write original code.** Copy nothing from another project.
48-- **No sandbox or permission layer.** Tools run with the user's permissions;
49- isolation is an environment concern, not the agent's.
50-- **No loop limits.** No max turns, tool calls, token budgets, or agent-imposed
51- timeouts (except for bash tool, agents are prone to running bad commands this is
52- guard against it). The user's ability to interrupt is the limit.
53-- **Config-first.** Every user-facing behavior that can vary comes from config
54- with a sane default. Global config only — no project-local config; a
55- `-c`/`--config` file overrides the global one for a run — and never duplicate
56- a provider's catalog or env vars.
57-- **Minimal context.** The model sees the configured system prompt plus
58- explicitly opted-in resource files — never reminders, hidden blocks, or
59- injected meta-text.
60-- **The agent never imports the TUI.** Headless and TUI are two projections of
61- the same agent events; the TUI owns no agent or provider semantics.
62-
63-## Invariants
64-
65-- Sessions are append-only JSONL, one message per line, fsynced on write. Never
66- rewrite or delete committed lines. A persistence failure stops the turn. Every
67- model step also records the exact request: system prompt, tools, provider,
68- model, api, and thinking effort.
69-- The loop has no compaction, no retries, and no meta-messages between steps.
70- Provider errors surface as-is, never masked or summarized. Steering typed at a
71- pause lands at the next step boundary, never between a turn and its results.
72-- `edit`, `read`, and `bash` only. Tool arguments are untrusted and validated
73- once at the boundary. `read` returns image blocks only for models that declare
74- image input.
75-- `bash` runs detached and kills its process group on cancel. Filesystem
76- snapshots before and after produce diffs for display only; they never reach
77- the model.
78-- Terminal output is fully specified: truecolor, an explicit palette for every
79- cell, no resets that could fall back to the host terminal, and untrusted text
80- sanitized of every escape sequence except SGR.
81-- Interruption: ESC politely pauses at the next step boundary; Ctrl+C cancels the
82- turn (abort the request, kill the tool's process group, persist the aborted
83- message); Ctrl+D exits on an empty draft. Completed side effects are never
84- undone.
85-- Diagnostics are local only. No telemetry, no hidden stalls.
86-
87-## Memory
88-
89-Manual memory bookkeeping is the largest fragility a program of this shape can
90-carry. Do not reintroduce it.
91-
92-- One allocator, chosen at startup, threaded explicitly. Long-lived state and
93- per-turn scratch are separate lifetimes, not one global pool.
94-- A turn's transient objects — stream accumulators, tool result text, images,
95- diffs, serialization buffers — die with the turn. Prefer arena or explicit
96- lifetime over scattered frees.
97-- **Never swallow an allocation failure.** A dropped message, a silently
98- truncated stream, or a `catch {}` on an append is a lost turn. Surface it
99- through the event stream as an error the user can see.
100-- No hidden global mutable state beyond the process-wide allocator and IO
101- handle, and those are set once at startup.
102-
1039 ## Verification
10410
10511 Verify against the real provider. **Do not stand up mock servers, fixture
@@ -126,17 +32,3 @@ its truecolor SGR to `final.txt` (scrollback) and `final-screen.txt` (live
12632 screen). The last line reports frames, wall time, and achieved fps; an
12733 `ended early: MINI-EXIT <n>` line means the app died, and `final.txt` holds the
12834 dump. Read the pane text and the frames, not pixels.
129-
130-## Working agreement
131-
132-- Trace the real data flow before designing; apply guards at the narrowest
133- boundary.
134-- Keep the diff small. Do not opportunistically refactor or harden adjacent code.
135-- Prefer plain functions and explicit allocators; keep exports minimal; define
136- helpers near their use.
137-- Validate untrusted input once at the boundary, then keep internal code
138- plain-typed with no runtime checks.
139-- Ask before adding a dependency.
140-- Do not add tests unless explicitly asked; verify manually.
141-- Before finishing, review the diff against the direction and guardrails, remove
142- anything that added scope, and report any requirement you could not satisfy.
ISSUES.md+0−11
@@ -1,11 +0,0 @@
1-# Issues from QA/Live use
2-
3-> The user owns this file, do not edit unless asked to.
4-> If there are edits, it's the user updating the file.
5-
6-- None
7-
8-# Improvements
9-
10-- Add to the banner a second line, that shows the count of AGENTS.md files loaded and the SKILL.md files loaded.
11-- When we start a new session, print a blank line, the banner, and then the "new session" label but dimmed.