execlaw AGENTS.md

AGENTS.md

Guide for AI coding agents (Claude Code, Cursor, Aider, etc.) working on this repo. The product itself is also a coding-capable agent platform — this doc is about agents editing execlaw, not agents running on execlaw.

If you are an agent and you have not yet read docs/architecture.md, do that first. The rest of this file assumes you've internalised the 12 design principles in §2 of that doc.

---

1. What this codebase is

execlaw is a self-hosted Rust agent framework. Single-operator, runs on the operator's hardware, no cloud LLMs ever. It's built around three load-bearing abstractions:

1. An append-only event log (SQLite, optionally SQLCipher-encrypted). Every action is a row in state_events; replay reconstructs state.
2. A plugin framework that loads ZIP bundles at runtime — manifest declares tools, sidecars, transports, identity providers, OAuth clients, webhook routes. Two runtime tiers: script (Rhai) and subprocess (JSON-RPC).
3. A trust ladder + Rule of Two policy gate that decides which tools the agent can call given the principal's trust class and the turn's sensitivity.

The Rust workspace lives in crates/. The SPA lives in web/. First-party plugins live in plugins/. Documentation lives in docs/ (architecture, agent-model, plugins, sidecar-supervisor, runner-design, voice-followups). Inline source comments still cite MIGRATION_PLAN.md §X for historical rationale; the file itself was retired once its content was distributed across the in-tree docs.

---

2. Non-negotiable rules

These are axioms. Violating any of them will require a re-do.

1. No cloud LLMs. Anthropic, OpenAI, Gemini, Mistral cloud — none of them, on any code path, ever. Inference happens against a local OpenAI-compatible endpoint (vLLM / OpenArc / similar). If a feature seems to require a cloud LLM, the answer is "design it differently or don't ship it."
2. Plugins, not hardcoded built-ins. If a host crate references a specific plugin id by name in production code (e.g. if plugin_id == "signal"), that's a leak. The host knows about plugins only through manifest-declared surfaces (registry lookups, capability gates). Test fixtures and doc-comment examples are fine.
3. SQLite is the source of truth. No environment variables for configuration, no .env files, no shared TOML/YAML in /etc. Operator-editable config lives in config_* tables; secrets live in the SQLCipher vault keyed by an OS-keyring master key.
4. Effects go through the outbox. The LLM never makes external HTTP calls directly. It emits a tool_use event; the host enqueues a state_outbox row with a framework-minted idempotency key; a separate relay drains it.
5. tool_use and tool_result always pair in the same commit. Enforced by EventLog::commit_turn::enforce_tool_pairing(). If a turn fails mid-tool, a synthetic cancellation tool_result must be committed alongside.
6. Tests are mandatory for non-trivial code. Per the project's axiom #13, every non-trivial function, every invariant, every public API has tests. Security-critical code has adversarial tests. cargo test --workspace must pass before any commit.
7. Performance regressions are blocked by Criterion benchmarks. Per axiom #14, hot paths have benchmarks with explicit budgets. Don't claim a speedup without numbers.
8. Never create commits without explicit human approval. A user asking you to fix a bug is not the same as authorising a commit. Wait for "commit", "push", or equivalent before invoking git.
9. Never push to main/master. The active branch is foundation. Force-pushing to anything other than your own ad-hoc branch requires explicit user permission.