Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

docs(agents): reduce AGENTS.md to the English-only rule (#726)

Ruben Lütke293caa4b5d50
diff --git a/AGENTS.md b/AGENTS.md
index d25c74021f..114c21a184 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,271 +1,3 @@
-# Dodaios agent rules
+# All code, comments, logs, and commits must be in **English**.
-The binding rules for every coding agent in this repo: Claude Code, Codex,
-Gemini CLI, whichever. Write everything here so it addresses ANY agent.
-
-**Source of truth:** `AGENTS.md` is the only instructions file; every agent
-reads it directly. Never add a `CLAUDE.md`, `.claude/CLAUDE.md` or
-`CLAUDE.local.md`: Claude Code then reads that file INSTEAD of this one
-(`scripts/ci/check_agents_md.py` blocks a tracked one). A Claude pane on a
-Dodaios account config dir sees `~/.claude/CLAUDE.md` as such a parent-dir file,
-so its user settings need the agents-md built-in plugin's `instructionFiles`
-option set to `claude-md-and-agents-md`.
-Edit `.agents/{agents,skills}/`; `.claude/{agents,skills}/` are compatibility
-copies because Claude Code does not discover subagents or skills under
-`.agents/`, and `.codex/agents/*.toml` is generated from `.agents/agents/*.md`
-for Codex. The sync scripts and CI check these copies; never edit a generated
-copy directly.
-
----
-
-## 1. Traps no one guesses
-
-These cost real bugs. Nothing catches them but you.
-
-- **Restore trap.** A fix works in tests and changes nothing after restart:
- live Python imports from elsewhere. New worktree → `pwsh scripts/preflight.ps1`,
- then `python -c "import jarvis; print(jarvis.__file__)"`. (AP-8) Never
- `pip install -e` from a linked worktree: that pin is the user's desktop app,
- and their next restart boots your branch with an empty `data/`. (BUG-219)
-- **`main` takes no local commits.** Local `main` mirrors `origin/main` and
- moves only by `git pull --ff-only`; the hooks refuse a commit on it and any
- other move (`update-ref`, cherry-pick, rebase) to a commit no remote has.
- Every change lives on a feature branch in a worktree of your own:
- `git worktree add -b <agent>/<topic> <path> origin/main`, one topic per
- branch. A commit on local `main` exists on one machine, and the squash-merging
- queue makes it diverge from the remote for good.
-- **The main checkout is SHARED** with other agent sessions and runs the user's
- desktop app. Never switch its branch, reset it or stash in it. Wherever a
- tree is shared, stage only YOUR paths — `git add -p` or an explicit pathspec,
- and `git commit --only -- <paths>`. `git add -A` sweeps someone else's
- half-finished work into your commit.
-- **A probe against the running app spends the user's real money.** Turns sent
- to it (`/ws`, `jarvis` CLI, Telegram) bill their own keys: five scripted
- test turns once cost $6.82 on a deep model. Send one turn, on a subscription
- or `tests/fakes/`, never a loop against a paid provider.
-- **`jarvis.toml` only through `jarvis/core/config_writer.py`** — lock, tempfile,
- BOM-safe. A raw write leaves the backend unbootable. (AP-7)
-- **Never share a native inference engine** (ctranslate2, ONNX) between callers.
- It wedges permanently and a timeout does NOT recover it: non-blocking
- per-instance lock + `recover()` that rebuilds a fresh model. (AP-24)
-- **Every `subprocess` passes `NO_WINDOW_CREATIONFLAGS`** from
- `jarvis.core.process_utils`, and stdout is UTF-8 (Windows defaults cp1252). (AP-1)
-- **Don't "clean up" the `openclaw` strings.** The external binary name and the
- read-time back-compat aliases are load-bearing; retired codenames stay dead
- everywhere else.
-- **A stall watchdog resets its counter per unit of work** (AP-19); a WebSocket
- receive loop treats ANY read error as terminal and breaks (AP-20); a subscriber
- exception never leaves `EventBus._safe_dispatch` (AP-18).
-- **Every reconnect is jittered and pays the shared connect budget.** A retry
- grid with no jitter, or a wake handler that opens a socket directly, is not
- an app bug: N panes x M windows x 2 instances firing on one
- `visibilitychange` empties the OS ephemeral-port pool and NOTHING on the
- machine can connect for two minutes. Frontend goes through
- `lib/connectBudget.ts`; a poll reuses a client from `jarvis/core/http_pool.py`.
- (AP-33)
-- **No invisible browsers.** UI checks, screenshots and scraping run in a tab of
- the user's real Chrome: never a headless/private Chrome, Playwright, Puppeteer
- or Selenium launch. Hidden Chromes once pinned the CPU at 100 % for hours. If
- the real browser is unreachable, report the visual check as unverified. Only
- a render job whose output is a file (video, HTML→PNG) may run headless: one
- at a time, and kill its whole process tree when it ends.
-- **No Windows Service** — SYSTEM has no microphone. (AP-17)
-- **Never gate a CI check on `isinstance` against an unpinned library.** Green
- locally, red in CI on the next release. Discriminate by capability. (AP-28)
-- **The desktop app is a WebView** — no F5, no console, no dev tools. A frontend
- fix is `npm run build` in `jarvis/ui/web/frontend/` and nothing else; open
- windows reload themselves (`src/lib/bundleWatch.ts`). Never end a frontend
- change by asking for a restart.
-- **Check your project memory before larger decisions** where your CLI keeps
- one (Claude Code loads its `MEMORY.md` index automatically).
-
-## 2. What the product is
-
-Assume an arbitrary downloader, never the maintainer — their box is <0.1 % of
-the install base, and "works on my machine" is the defect. (AP-23)
-
-- **Any single key must work.** Gate on capability, never a provider name or
- model id (AP-21). A tier whose primary AND fallback share one provider family
- is a brick — every chain crosses families or degrades honestly (AP-22).
-- **Bypass permissions is the project default.** Fresh installs, chats, agents,
- delegated work and coding panes execute permitted work without asking for
- permission. Carry this default into native CLI launch flags too; an omitted
- pick must not restore a vendor's ask-first default. Preserve explicitly
- selected restrictions and blocked actions. Questions for missing task
- information remain available; do not turn them into permission prompts.
-- **Nothing the user did not start may bill a key on its own.** Health dots
- come from real calls, never a paid probe. Once a subscription is connected,
- background work runs only on subscriptions or local models
- (`jarvis/brain/background_policy.py`); a failing subscription makes it WAIT,
- never fall back to an API key. An agent's own memory updates run on that
- agent's seat. Idle once burned 5 EUR in three hours on wiki calls.
-- **Every OS**, including a headless `python:3.11-slim` with no GPU, audio or
- native API: base install + boot must succeed there. Extras group, environment
- marker or lazy import — whichever fits.
-- **Credentials are recoverable IN-APP** (keyring → ENV → file). Never make
- someone hand-edit `jarvis.toml` or export a variable.
-- **Enumerate providers from the CODE** (`jarvis/core/config.py`,
- `jarvis/realtime/factory.py`), never from this box's `jarvis.toml`.
-- **Everything committed is ENGLISH** — code, comments, docstrings, logs, commit
- messages. German only on the closed product surface: runtime voice/chat output,
- i18n files, speech-input vocabulary, and tests quoting them
- (`scripts/ci/german-allowlist.txt`, inline `i18n-allow`). Translate legacy
- German in files you touch. Runtime output language is decided ONCE per turn by
- `jarvis/core/turn_language.py`; no layer re-derives it, all locales are equal.
-
-**Public product descriptions.** Treat tracked documentation, source comments,
-docstrings, test descriptions, video copy, and commit/PR/release text as public.
-Describe our features and interactions directly. Do not present another product
-as a design reference or say our UI or behavior is inspired by, modeled on,
-copied from, or made to match it. Preserve required copyright, license and
-attribution notices and factual dependency, integration and compatibility
-references; this rule never authorizes concealing code provenance. Competitor
-research stays out of the repo. `scripts/ci/check_design_references.py` checks
-staged lines at commit time and the whole tree in CI.
-
-**Proportionality.** You own the validation plan: the smallest set of checks
-that can detect a plausible regression from the diff. State the scope, what
-ran, and what remains unverified in the PR. Tiers are guidance, not checklists:
-
-- **T1 local:** for copy, styling, docs, one view, or an isolated refactor, run
- focused checks for that surface. A frontend change still needs a production
- build and light/dark inspection when its appearance changes.
-- **T2 one surface:** test the affected adapter, transport, channel, or OS
- backend and its nearest callers. Check other platforms when the changed path
- can execute there; state why an unavailable platform is unaffected or how it
- degrades.
-- **T3 shared contract:** prove the changed behavior with contract tests and
- exercise the affected providers and OSes. Update `docs/os-parity.md` when OS
- behavior changes. A new provider or credential path needs a fresh-install,
- one-key proof; a schema-only change does not automatically owe that test.
-
-Escalate evidence when risk crosses a boundary. Never claim an unrun platform,
-device or provider was verified. A check red on the exact base commit: compare
-failure identities and causes in the same environment (counts are not a
-comparison); a failure already on base is a backlog item, a new or changed
-failure blocks completion. Never silence a required check, raise a baseline,
-or bypass branch protection to look green.
-
-## 3. Architecture you must respect
-
-Higher layers reach lower ones only through `jarvis/core/protocols.py`; lateral
-traffic is `frozen=True` events on `EventBus` carrying `trace_id`. Plugins live
-under `jarvis/plugins/<group>/`, register via entry-points, import no `jarvis.*`
-(then `pip install -e . --no-deps`). Brain/STT/TTS/Harness are streaming-first.
-Secrets only via `get_secret` — never in code, `jarvis.toml`, or a commit, and
-voice/chat must never accept one (AP-2). Signing private keys live only in
-GitHub Actions secrets (AP-29). The router is a pure dispatcher over
-`ROUTER_TOOLS` (ADR-0011) and no spawn tool ever enters a worker set (AP-5/14);
-extending it means amending the ADR and `test_routing.py`. `scrub_for_voice` is
-regex-only, never an LLM call (AP-11). Any value crossing Python ↔ SQL ↔ Pydantic
-↔ TS ↔ UI uses the five-layer pattern plus a parity test (AP-4). Mission workers
-run in a fresh `git worktree` with kill-on-crash containment (AP-10). Nothing
-initializes on the boot critical path (AP-26). Risk tiers are safe / monitor /
-ask / block with blacklist > whitelist > default; only `ToolExecutor.execute()`
-is authorized (AP-3), and generated skills stay `draft` (AP-15).
-
-Two the gates catch but models still write: never swallow an exception without
-logging, re-raising, or saying why silence is right (AP-30), and never add a
-config field nothing reads (AP-31).
-
-Marketplace plugin auth: before touching a plugin or the catalog, read
-`docs/marketplace/browser-auth-standard.md` (one browser approval, zero
-developer setup, publisher-provisioned OAuth client, verified/preview
-acceptance from real browser evidence). BLOCKED never means verified.
-
-The rest of the register, one line each, because code comments cite these
-numbers: never hardcode an Anthropic/Claude client (AP-6); keep awareness and
-wiki code off the voice critical path (AP-9); never put a key in `jarvis.toml`
-or commit `.env` (AP-12); never block on a watchdog reload to verify an atomic
-write (AP-13); never reintroduce a sub tier or `SUB_TOOLS` set — Wave 4 deleted
-it (AP-14); new `[phase6.*]` / `[memory.wiki.*]` keys need
-`ConfigDict(extra="allow")` or pre-validate rejects them (AP-16); gate the GPU
-wake upgrade only on the out-of-process inference probe, never on CUDA presence
-(AP-25); verify a wake word on audio energy and candidate shape, never on
-transcript content (AP-27); a WebGL scene releases its context and survives
-losing it (AP-32); a reconnect pays the jittered connect budget (AP-33, §1); a macOS
-feature asks the OS at first use, from a user gesture, through
-`jarvis/platform/permission_service.py` — no preflight refuses before the OS was
-asked, nothing is asked at launch, nothing acts without a live grant, an agent
-never answers a system dialog (AP-35; `docs/macos-permissions.md`, ADR-0038).
-Detail and history for any of them: `docs/BUGS.md`.
-
-## 4. How work ships
-
-**World and character art:** use the `game-art-pipeline` skill
-(`docs/agent-society/game-art-pipeline.md`) before creating or redesigning
-game assets.
-
-Commit each finished step (Conventional Commits). Use the coding agent's
-standard Git workflow: do not artificially leave completed work local, and do
-not wait for extra Dodaios permission to commit, branch, push, or open
-a pull request. Once the scoped review and required checks pass, the agent may
-merge an ordinary authorized PR without another confirmation; a draft PR stays
-draft until its remaining work is done. Cut each branch from a freshly fetched
-`origin/main`; once its PR has merged, fast-forward the main checkout
-(`git pull --ff-only`) so the desktop app runs the landed code. Never
-`--force`, never `--no-verify`. Isolated mission workers must not run git
-(`add`/`commit`/`branch`/`checkout`/`push`) — the parent runtime captures the
-diff and lands it. Never push from a linked mission worktree. **A push is
-`git push`:** nothing is built, cloned, audited, or reviewed on the way.
-Review happens when code is written, never when it is published. A check that
-reads the whole tree belongs in CI, never in `pre-push`. A release (SemVer +
-tag + CHANGELOG + published GitHub Release) happens ONLY when explicitly
-asked — an ordinary push is not a release. A release is ONE command:
-`gh workflow run release-cut.yml -f bump=patch|minor|major` (pick the bump from
-the commits since the last tag), then watch the run and report the Release URL.
-There is no approval pause: only the release bot (and admins) may create a
-`v*` tag, and the signing keys and PyPI (environments `release-signing`,
-`pypi`) are reachable only from `v*` tag runs. That workflow bumps, writes the CHANGELOG, tags, waits for CI and publishes;
-never bump, tag or `gh release create` by hand.
-
-Every frontend change works in BOTH light and dark mode, and on the terminal
-panes' own appearance — colours come from theme tokens or the per-appearance
-tables in `terminalThemes.ts`, never one hardcoded mode.
-
-**Runtime restarts:** agents may restart the desktop app and related development
-processes when needed to apply or verify authorized work, without asking for
-additional approval. Announce the reason, prefer programmatic lifecycle/process
-control over desktop UI automation, and verify that the application returns
-healthy. This does not authorize stopping
-unrelated processes or leaving the desktop app shut down.
-
-Local model defaults (Ollama/llama.cpp) are checked against the live catalog
-when changed; nothing a year old or older ships as a default.
-
-## 5. Run & test
-
-`pip install -e . --no-deps` + `-r requirements.txt` + `".[dev]"`; launch
-`run.bat` (`--headless` = API only). Choose focused `pytest` and lint targets
-for the diff; use fakes from `tests/fakes/`, never `unittest.mock`. Run the
-full suite when a change has broad reach or focused tests cannot bound its
-risk. New providers pass their `tests/contract/` family. Four guards always run
-inside `CI gate`: `test_routing`, `test_output_filter`,
-`test_hangup_reason_parity`, `test_turn_language`.
-
-The commit and push hooks block confirmed secret, private-key, withheld-path,
-language, and broken-bundle additions. CI (`docs/ci-pipeline.md`) has ONE
-required check, `CI gate`, over change-classified lanes; a test failure blocks
-unless it is listed in `scripts/ci/test-baseline-<os>.json`. Finished work in
-your own worktree lands with `python scripts/agent_land.py` (rebase onto main,
-auto-resolve generated files, gates, relevant tests, push); a `codex/`,
-`claude/`, `agent/` branch or an `auto-merge` label puts a PR on the merge
-train, which resolves its conflicts with main and adds it to main's merge
-queue once green; the queue squash-merges it after `CI gate` passes again on
-the PR merged with the newest main. The train enqueues only with its bot
-token: `agent_land.py` therefore requests auto-merge, and a PR opened any
-other way needs `gh pr merge <branch> --auto --squash` once, or it waits for
-a person. A pull request runs Linux and Windows; the merge queue adds the
-macOS tests the change can reach; the rest of macOS runs nightly and on
-release (`docs/ci-pipeline.md`, Tiers). Direct pushes to main are blocked for
-everyone but admins.
-Triage any red job against the exact base; never add to a baseline to hide a
-new failure.
-Run `check_boot_budget.py` after touching startup; CI cannot measure the live
-voice-ready path.
-
-**Pointers:** [`docs/architecture-overview.md`](docs/architecture-overview.md) ·
-[`docs/BUGS.md`](docs/BUGS.md) (symptom → cause) · `docs/adr/` ·
-[`docs/os-parity.md`](docs/os-parity.md) ·
-[`docs/macos-permissions.md`](docs/macos-permissions.md) ·
-[`docs/jarvis-cli.md`](docs/jarvis-cli.md).
+# your mind creates the world
\ No newline at end of file