cezar AGENTS.md

AGENTS.md — working in this repository

cezar is a parallel coding-agents orchestrator: a local cockpit (CLI + browser GUI) for running and tracking AI coding-agent tasks in a repo. You type a task, pick a workflow and a backend — Claude Code, Codex or OpenCode (experimental), or a mix per step — and watch it work live: steps, tool calls, tokens, diffs. Each task runs in its own git worktree, ends at a review gate (never auto-merges), and can be pushed as a draft PR through gh. Everything is local: no accounts, no database, no cloud — state is plain JSON, NDJSON and Markdown under .ai/cezar/. The server stack stays deliberately small: strict TypeScript (ESM, Node 20+), Hono + SSE, Zod at every boundary, and YAML workflows. The cockpit is React 19 + Vite + Tailwind v4 + shadcn/ui, compiled to static assets (the legacy vanilla UI was retired in R7). Every module is meant to be read in one sitting.

Zero config

cezar ships no config file the user must create and no setting they must set before it works. Every capability is discovered from what is already there — the repo, the environment, gh, the running processes — or it degrades quietly to a smaller cezar. .ai/cezar/config.json is optional and every key has a working default; .env is never auto-loaded.

New state may be written, never required: .ai/cezar/, ~/.cache/cez/, ~/.cezar/. Delete any of them and cezar rebuilds what it needs on the next run. State that a user must author, migrate, or repair is not state — it is configuration, and it needs a reason. One deliberate exception inside that rule: the project registry keeps a ~/.cezar/config.json.bak snapshot, so deleting config.json alone restores instead of resetting — delete the ~/.cezar directory for a true reset.

Practical rules:

• When a feature seems to need configuration, the design is wrong. Discover it, or default it.
• Features that widen exposure or cost (network, other processes) are opt-in behind a CEZ_* flag, off by default — the zero-config default is also the safe default.
• Owner-approved exception: Open Mercato skill updates are default-on. They start only after the server listens, run at most once per six-hour cache window, use explicit lock-authorized names and fixed bounded npx argument arrays under a cross-process lock, and never block boot. CEZ_SKILLS_AUTO_UPDATE=0 or the global Settings override disables automatic application (background detection remains read-only).
• A missing dependency, an absent peer, a read-only home: degrade to a smaller working cockpit, never fail the boot.
• Prefer a proxy-free, daemon-free mechanism when one exists — and when it doesn't, keep the mechanism invisible: no process to manage, no port to remember, no file to edit.
• Never trade a working default for a knob.
• Adding, renaming, or removing a CEZ_* env var — or changing what its default does — MUST update .env.example in the same commit (and the README env table when the var is user-facing). .env.example is the env contract's single documentation surface; an undocumented env var is a bug.